From 49971a8130cc3a38387869344ec6f25b9423bc63 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:08:55 +0200 Subject: [PATCH 01/14] docs: plan readonly-view v2 launch --- .../2026-09-03-legal-deployment-release.md | 365 ++++++++++++++++++ ...6-09-03-legal-deployment-release-design.md | 69 ++++ 2 files changed, 434 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-03-legal-deployment-release.md create mode 100644 docs/superpowers/specs/2026-09-03-legal-deployment-release-design.md diff --git a/docs/superpowers/plans/2026-09-03-legal-deployment-release.md b/docs/superpowers/plans/2026-09-03-legal-deployment-release.md new file mode 100644 index 0000000..837316f --- /dev/null +++ b/docs/superpowers/plans/2026-09-03-legal-deployment-release.md @@ -0,0 +1,365 @@ +# ReadonlyView Legal, Deployment, and Stable Release Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add bilingual legal pages, production Vercel deployment, reference-grade GitHub automation, and publish `@nipe-solutions/readonly-view@2.0.0` as a verified stable release. + +**Architecture:** Keep the Vite site framework-free and add four static legal entry points sharing the existing design system. Use Vercel Git integration for preview/production deployments and the guarded GitHub release workflow for npm OIDC publication after all local and hosted checks pass. + +**Tech Stack:** HTML, CSS, TypeScript, Vite 8, Playwright, GitHub Actions, Vercel, GoDaddy DNS, npm trusted publishing. + +**Spec:** `docs/superpowers/specs/2026-09-03-legal-deployment-release-design.md` + +## Global Constraints + +- Publish exactly `@nipe-solutions/readonly-view@2.0.0` publicly under `latest`. +- Use `https://readonly-view.nipesolutions.com` as the production documentation origin. +- Preserve zero runtime dependencies and the framework-free Vite website. +- Reuse the approved NIPE Solutions e.U. legal operator data and bilingual reference text. +- Do not publish until the release commit is merged to `main`, CI is green, and the exact tarball is verified. +- Do not deprecate or otherwise mutate the old `immuview` npm package. + +--- + +### Task 1: Bilingual legal routes and production website metadata + +**Files:** +- Create: `website/privacy/index.html` +- Create: `website/impressum/index.html` +- Create: `website/de/datenschutz/index.html` +- Create: `website/de/impressum/index.html` +- Create: `website/legal.css` +- Create: `website/public/robots.txt` +- Create: `website/public/sitemap.xml` +- Create: `website/public/favicon.svg` +- Create: `website/public/favicon-32x32.png` +- Create: `website/public/apple-touch-icon.png` +- Create: `website/public/site.webmanifest` +- Modify: `website/index.html` +- Modify: `website/styles.css` +- Modify: `vite.website.config.ts` +- Modify: `scripts/verify-website.mjs` +- Modify: `test/browser/website.spec.ts` +- Modify: `test/integration/docs-examples.test.ts` + +**Interfaces:** +- Consumes: existing `.masthead`, `.brand`, footer, color tokens, and `npm run build:website`. +- Produces: four stable legal routes, language cross-links, canonical production URLs, and multi-page Vite output under `website/dist`. +- Produces: a crisp ReadonlyView tab-icon family derived from the existing `R` brand mark. + +- [ ] **Step 1: Add failing build-verification assertions** + +Extend `scripts/verify-website.mjs` to read all five built HTML files and assert their defining content: + +```js +const pages = new Map([ + ['privacy/index.html', ['Privacy Policy', 'Vercel Inc.', 'no non-essential cookies']], + ['impressum/index.html', ['Impressum', 'NIPE Solutions e.U.', 'ATU78464412']], + ['de/datenschutz/index.html', ['Datenschutzerklärung', 'Vercel Inc.', 'Datenschutzbehörde']], + ['de/impressum/index.html', ['Impressum', 'NIPE Solutions e.U.', 'FN 585066t']], +]); +``` + +Also assert that the main page links each route and no page contains `v2 alpha`. + +Assert that the home page contains examples for nested protection, owner-side live updates, arrays, Map, Set, Date, cycles, shared identity, and mutation rejection. + +Assert that all pages link `/favicon.svg`, `/favicon-32x32.png`, `/apple-touch-icon.png`, and `/site.webmanifest`, and that every referenced asset exists in `website/dist`. + +- [ ] **Step 2: Run the website check and confirm it fails** + +Run: `npm run test:website` + +Expected: failure because the legal build outputs do not exist. + +- [ ] **Step 3: Add the legal HTML and shared legal layout** + +Create semantic pages with one `h1`, a last-updated date, language switch, linked email/phone, company details, and the approved English/German privacy sections. Use a shared `.legal-shell`, `.legal-content`, and `.legal-meta` layout in `website/legal.css`; retain `:focus-visible` and a one-column mobile breakpoint. + +- [ ] **Step 4: Configure the Vite multi-page build** + +Change `vite.website.config.ts` to resolve these inputs: + +```ts +rollupOptions: { + input: { + index: resolve(import.meta.dirname, 'website/index.html'), + privacy: resolve(import.meta.dirname, 'website/privacy/index.html'), + impressum: resolve(import.meta.dirname, 'website/impressum/index.html'), + datenschutz: resolve(import.meta.dirname, 'website/de/datenschutz/index.html'), + 'de-impressum': resolve(import.meta.dirname, 'website/de/impressum/index.html'), + }, +}, +``` + +Use root-absolute asset and navigation URLs because production routes are nested. + +- [ ] **Step 5: Update the home page, examples, and crawl metadata** + +Create an original SVG favicon with a dark rounded-square core, white `R`, and blue membrane accent. Render deterministic 32×32 and 180×180 PNG variants from that SVG, add a minimal web manifest, and add favicon, Apple-touch, manifest, and theme-color tags to every page. + +Remove the hero release-status pill entirely. Move `v2` and `zero runtime dependencies` into the proof/metadata area, add canonical/OG production URLs, and add footer links to all legal pages. Add copyable examples for nested objects, owner-side live updates, arrays, Map, Set, Date, cycles, shared identity, and mutation rejection. Add `robots.txt` and a sitemap containing the five canonical URLs. + +Extend `test/integration/docs-examples.test.ts` with executable equivalents of the new examples, including: + +```ts +const shared = { id: 1 }; +const source = { + items: [shared], + map: new Map([['selected', shared]]), + set: new Set([shared]), +}; +const view = readonlyView(source); +expect(view.items[0]).toBe(view.map.get('selected')); +expect([...view.set][0]).toBe(view.items[0]); +expect(() => Reflect.set(view.items[0], 'id', 2)).toThrow( + DirectMutationError, +); +``` + +- [ ] **Step 6: Add browser route coverage** + +Add a Playwright test that opens each route and checks its heading, language link, footer, and absence of horizontal overflow: + +```ts +for (const [route, heading] of legalRoutes) { + await page.goto(route); + await expect(page.getByRole('heading', { level: 1, name: heading })).toBeVisible(); + expect(await page.evaluate(() => document.body.scrollWidth)).toBeLessThanOrEqual( + await page.evaluate(() => document.documentElement.clientWidth), + ); +} +``` + +- [ ] **Step 7: Verify and commit** + +Run: `npm run test:website && npm run test:browser -- --project=chromium` + +Expected: all website and Chromium tests pass. + +Commit: `feat(website): add bilingual legal pages` + +### Task 2: Vercel configuration and public metadata + +**Files:** +- Create: `vercel.json` +- Modify: `package.json` +- Modify: `package-lock.json` +- Modify: `README.md` +- Modify: `SECURITY.md` +- Modify: `docs/compatibility.md` +- Modify: `scripts/verify-release.mjs` + +**Interfaces:** +- Consumes: `npm run build:website` and `website/dist` from Task 1. +- Produces: repeatable Vercel builds and a single canonical documentation origin across metadata. + +- [ ] **Step 1: Add failing metadata verification** + +Extend `scripts/verify-release.mjs` with exact assertions: + +```js +assert(pkg.homepage === 'https://readonly-view.nipesolutions.com', 'Homepage is stale'); +const vercel = JSON.parse(await readFile(resolve(root, 'vercel.json'), 'utf8')); +assert(vercel.buildCommand === 'npm run build:website', 'Unexpected Vercel build'); +assert(vercel.outputDirectory === 'website/dist', 'Unexpected Vercel output'); +``` + +- [ ] **Step 2: Confirm the release verifier fails** + +Run: `node scripts/verify-release.mjs` + +Expected: failure because package homepage and `vercel.json` are not production-ready. + +- [ ] **Step 3: Add Vercel configuration** + +Create: + +```json +{ + "$schema": "https://openapi.vercel.sh/vercel.json", + "buildCommand": "npm run build:website", + "framework": null, + "installCommand": "npm ci", + "outputDirectory": "website/dist" +} +``` + +- [ ] **Step 4: Update public URLs and package version** + +Run `npm version 2.0.0 --no-git-tag-version`, set `homepage` to the production domain, and update README, security, and compatibility links. Confirm both `package-lock.json` version fields equal `2.0.0`. + +- [ ] **Step 5: Verify and commit** + +Run: `npm run build:website && node scripts/verify-release.mjs` + +Expected: both commands pass for `@nipe-solutions/readonly-view@2.0.0`. + +Commit: `chore(release): prepare v2 production metadata` + +### Task 3: Reference-grade CI and guarded release workflow + +**Files:** +- Modify: `.github/workflows/ci.yml` +- Modify: `.github/workflows/release.yml` +- Modify: `docs/RELEASING.md` +- Modify: `CONTRIBUTING.md` + +**Interfaces:** +- Consumes: `npm run release:check`, Playwright projects, packed artifact output, npm channel verifier. +- Produces: dependency-ordered CI, failure diagnostics, and a stable-only guarded release path using GitHub environment `npm`. + +- [ ] **Step 1: Validate workflow syntax before edits** + +Run: `npx prettier --check .github/workflows/ci.yml .github/workflows/release.yml` + +Expected: pass, establishing the existing baseline. + +- [ ] **Step 2: Align the CI workflow** + +Use `actions/checkout@v7`, retain `actions/setup-node@v7` and `actions/upload-artifact@v7`, change primary quality to `npm run release:check`, make Node 22 and browser jobs depend on `quality`, and upload `playwright-report/` plus `test-results/` only on browser failure. Keep Chromium, Firefox, WebKit, packed artifact, Node 22, concurrency, and read-only permissions. + +- [ ] **Step 3: Tighten stable release validation** + +Use `actions/checkout@v7`, keep exact confirmation `publish 2.0.0 with latest`, require `main`, use environment `npm`, grant `id-token: write` only to publish, verify `2.0.0` is absent before publish, then verify registry propagation before the GitHub release. Preserve generic version inputs for future releases but enforce stable/latest through `verify-release-channel.mjs`. + +- [ ] **Step 4: Document hosted deployment and publication** + +Update `docs/RELEASING.md` and `CONTRIBUTING.md` with Vercel Git behavior, custom domain, npm environment/trusted-publisher tuple, exact dispatch inputs, post-publish checks, and rollback/non-republish guidance. + +- [ ] **Step 5: Verify and commit** + +Run: `npm run format:check && npm run lint && node scripts/verify-release-channel.mjs latest` + +Expected: all commands pass. + +Commit: `ci: align deployment and stable release gates` + +### Task 4: Finalize changelog and verify the release candidate + +**Files:** +- Modify: `CHANGELOG.md` +- Modify: `docs/release-readiness.md` + +**Interfaces:** +- Consumes: completed Tasks 1–3 and version `2.0.0`. +- Produces: an auditable stable changelog and exact local release evidence. + +- [ ] **Step 1: Promote release notes** + +Leave an empty `## Unreleased` section and move the complete v2 notes beneath `## 2.0.0 - 2026-09-03`, retaining Breaking Changes, Added, Fixed, Performance, and Documentation headings. + +- [ ] **Step 2: Run the practical local gate** + +Run: `npm ci && npm run release:check` + +Expected: formatting, lint, TypeScript, 65+ semantic tests, type tests, size, packed consumers, website verification, benchmark smoke, release metadata, and tarball creation all pass. + +- [ ] **Step 3: Run the browser matrix** + +Run: `npm run test:browser` + +Expected: Chromium, Firefox, and WebKit pass, except the repository's documented macOS 14 WebKit exclusion when applicable. + +- [ ] **Step 4: Inspect the exact package** + +Run: `npm pack --dry-run --json` and `tar -tzf .artifacts/nipe-solutions-readonly-view-2.0.0.tgz` + +Expected: only package metadata, README, LICENSE, changelog, and intended `dist` files; no tests, website source, benchmarks, source maps, or private modules. + +- [ ] **Step 5: Record measurements and commit** + +Update `docs/release-readiness.md` with exact test totals, tarball sizes, minified/gzip sizes, browser results, and the pending hosted steps. + +Commit: `docs: finalize readonly-view 2.0.0 release notes` + +### Task 5: Review, merge, and Vercel production deployment + +**Files:** +- External: GitHub pull request and CI +- External: Vercel project for `NIPE-Solutions/readonly-view` +- External: GoDaddy DNS for `nipesolutions.com` + +**Interfaces:** +- Consumes: reviewed release branch and `vercel.json`. +- Produces: green `main`, Vercel preview/production deployments, DNS verification, and valid HTTPS at the production origin. + +- [ ] **Step 1: Push and open a focused pull request** + +Push the release-preparation branch, open a PR against `main`, and include legal routes, workflow deltas, local gate evidence, package version, and explicit statement that npm is not yet published. + +- [ ] **Step 2: Review CI and preview deployment** + +Wait for quality, Node 22, Chromium, Firefox, WebKit, and Vercel preview checks. Open the preview and verify the home page plus all legal routes on desktop and mobile. + +- [ ] **Step 3: Merge and verify production CI** + +Merge only after all required checks pass, then wait for the `main` CI run to finish successfully. + +- [ ] **Step 4: Link the Vercel project** + +In the authenticated Vercel account, import `NIPE-Solutions/readonly-view`, select the appropriate NIPE Solutions team, confirm production branch `main`, and verify that Vercel reads the committed build and output settings. + +- [ ] **Step 5: Configure the custom domain** + +Add `readonly-view.nipesolutions.com` to the Vercel project, read the exact required DNS record, create that record in the authenticated GoDaddy account, and wait for Vercel to report a valid configuration and issued TLS certificate. + +- [ ] **Step 6: Verify production** + +Check status 200, canonical URL, title, home interaction, all four legal routes, sitemap, robots, and HTTPS using both browser inspection and HTTP requests. + +### Task 6: npm trusted publishing and irreversible stable release + +**Files:** +- External: GitHub environment `npm` +- External: npm organization/package trusted-publisher settings +- External: GitHub Actions Release run +- External: npm package and GitHub release + +**Interfaces:** +- Consumes: green merge commit on `main`, exact version `2.0.0`, npm organization access, production documentation. +- Produces: public `@nipe-solutions/readonly-view@2.0.0`, `latest` dist-tag, provenance, and GitHub `v2.0.0` release. + +- [ ] **Step 1: Configure GitHub release protection** + +Create the repository environment `npm`, restrict it to `main`, and add the authenticated owner as a required reviewer when the repository plan supports reviewers. Do not add a long-lived npm token. + +- [ ] **Step 2: Configure npm trusted publishing** + +In npm organization/package settings, configure repository `NIPE-Solutions/readonly-view`, workflow `release.yml`, environment `npm`. If npm cannot create the package through OIDC, perform only the minimum authenticated first-publication setup allowed by npm, then retain OIDC for future releases. + +- [ ] **Step 3: Reconfirm registry absence and commit identity** + +Run: `npm view @nipe-solutions/readonly-view@2.0.0 version` + +Expected before publication: npm `E404`. Confirm the release workflow SHA equals the reviewed green `main` SHA. + +- [ ] **Step 4: Dispatch the release** + +Run: + +```bash +gh workflow run release.yml --ref main \ + -f version=2.0.0 \ + -f channel=latest \ + -f 'confirmation=publish 2.0.0 with latest' +``` + +Approve the protected `npm` environment deployment when prompted and monitor every job through registry propagation and GitHub release creation. + +- [ ] **Step 5: Verify the public package** + +Run: + +```bash +npm view @nipe-solutions/readonly-view@2.0.0 name version dist-tags.latest repository homepage +npm exec --yes --package=@nipe-solutions/readonly-view@2.0.0 -- \ + node -e "import('@nipe-solutions/readonly-view').then(m => console.log(typeof m.readonlyView))" +gh release view v2.0.0 --repo NIPE-Solutions/readonly-view +``` + +Expected: exact name/version, `latest` equals `2.0.0`, production homepage, import prints `function`, provenance is visible in npm, and the GitHub release exists. + +- [ ] **Step 6: Record final release evidence** + +Update the release-readiness record or GitHub release notes with the production site, CI run, npm version, provenance, tarball integrity, and known limitations. Do not modify the old `immuview` package. diff --git a/docs/superpowers/specs/2026-09-03-legal-deployment-release-design.md b/docs/superpowers/specs/2026-09-03-legal-deployment-release-design.md new file mode 100644 index 0000000..4b93d68 --- /dev/null +++ b/docs/superpowers/specs/2026-09-03-legal-deployment-release-design.md @@ -0,0 +1,69 @@ +# ReadonlyView Legal, Deployment, and Stable Release Design + +**Status:** Approved on 2026-09-03 + +## Outcome + +ReadonlyView will expose complete bilingual legal pages, deploy its Vite documentation site through Vercel at `https://readonly-view.nipesolutions.com`, align repository automation with the NIPE Solutions reference repository, and publish `@nipe-solutions/readonly-view@2.0.0` under npm's `latest` tag. + +## Legal pages + +The site will publish four stable routes: + +- `/privacy/` +- `/impressum/` +- `/de/datenschutz/` +- `/de/impressum/` + +The text and operator data will be adapted from the NIPE Solutions React Spring Bottom Sheet v5 site. The operator is NIPE Solutions e.U., proprietor Nicholas Petrasek, Achtergasse 10, 1230 Wien, Austria. Contact, VAT, company-register, court, authority, chamber, and trade details remain identical to the approved reference pages. Privacy text will describe Vercel hosting, ordinary request logs, email/contact handling, no non-essential cookies or analytics, GDPR rights, and the Austrian data-protection authority. The pages must not claim legal guarantees beyond the source text. + +Legal pages use the established ReadonlyView visual system: shared masthead and footer, narrow readable measure, explicit language switching, keyboard-visible focus styles, and responsive layouts. The main footer links all English and German legal routes. + +## Website architecture + +The existing framework-free Vite website remains in place. Legal pages are static HTML entry points with shared CSS; Vite is configured as a multi-page build so route directories produce deployable `index.html` files. The site remains zero-JavaScript on legal routes and retains the current interactive module only on the documentation home page. + +The hero contains only the product proposition, install command, and interactive ownership demonstration. It must not use a release-status pill or the phrase `v2 alpha · zero runtime dependencies`. Version and zero-dependency facts belong in the quieter proof/metadata area. + +The documentation home includes concise, copyable code examples for nested objects, owner-side live updates, arrays, Map, Set, Date, circular references, shared identity, and rejected mutations. Examples use the real public API, remain short enough to scan, and are mirrored by automated documentation-example tests rather than presented as decorative code. + +Production metadata, canonical URLs, Open Graph URLs, sitemap, robots file, package homepage, and repository documentation use `https://readonly-view.nipesolutions.com`. + +The tab icon uses the established ReadonlyView brand mark rather than a generic shield or lock: a dark rounded-square `R` core with a blue membrane accent, simplified for legibility at 16×16. The site ships a scalable SVG favicon plus raster browser and Apple-touch variants, with theme colors and manifest metadata shared by every page. + +## Vercel and DNS + +The repository will include a `vercel.json` with `npm ci`, `npm run build:website`, and `website/dist` output. The GitHub repository will be connected to Vercel using Git integration: pull requests receive preview deployments and `main` is the production branch. The custom domain is `readonly-view.nipesolutions.com`; its exact Vercel-provided DNS record will be configured in GoDaddy and verified rather than guessed. + +## GitHub workflows + +Automation follows the reference repository's sequencing and supply-chain model without importing React-specific jobs: + +- current pinned major versions for checkout, Node setup, and artifact upload; +- Node 24 primary quality gate and retained Node 22 compatibility gate; +- browser jobs depend on quality and cover Chromium, Firefox, and WebKit; +- Playwright diagnostics upload only on failure; +- release runs only from `main`, requires exact version/channel/confirmation, verifies package and registry state, uses the protected `npm` environment and OIDC trusted publishing, verifies propagation, and creates a GitHub release; +- packed artifact verification, declaration checks, size budgets, website build, and benchmarks remain required. + +Vercel deployment uses Vercel Git integration, not duplicated GitHub Actions deployment secrets. + +## Stable npm publication + +The package name is `@nipe-solutions/readonly-view`, version `2.0.0`, visibility public, and distribution tag `latest`. Package metadata and the lockfile must agree. The changelog will contain a real `2.0.0` entry and a fresh empty `Unreleased` section. + +Before publication, the exact packed artifact must pass the full release check and browser matrix. npm trusted publishing will be configured for `NIPE-Solutions/readonly-view`, workflow `release.yml`, environment `npm`, if npm permits initial publication through OIDC. If the registry requires an authenticated first publication, the first release may use the already authenticated npm organization account, but it must still publish the verified artifact with provenance when supported. Publication is followed by registry import checks, provenance inspection, and a GitHub `v2.0.0` release. + +The old `immuview` package is outside this change and will be deprecated separately by the owner. + +## Release order + +1. Add and test legal pages and production metadata. +2. Align workflows and release documentation. +3. Run the full local quality, package, website, and browser gates. +4. Merge the reviewed release-preparation branch to `main` and wait for green CI. +5. Link and deploy Vercel, configure GoDaddy DNS, and verify HTTPS/routes. +6. Configure npm/GitHub trusted publishing and protection. +7. Dispatch the stable release and verify npm and GitHub release state. + +Public npm publication must not precede a green release commit on `main`. From d832879296234de180ff3cfded33d7b525562d60 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:18:04 +0200 Subject: [PATCH 02/14] feat(website): add bilingual legal pages --- scripts/verify-website.mjs | 105 +++++++++++++- test/browser/website.spec.ts | 26 ++++ test/integration/docs-examples.test.ts | 61 +++++++++ vite.website.config.ts | 29 +++- website/de/datenschutz/index.html | 181 +++++++++++++++++++++++++ website/de/impressum/index.html | 140 +++++++++++++++++++ website/impressum/index.html | 151 +++++++++++++++++++++ website/index.html | 125 +++++++++++++++-- website/legal.css | 106 +++++++++++++++ website/privacy/index.html | 174 ++++++++++++++++++++++++ website/public/apple-touch-icon.png | Bin 0 -> 5214 bytes website/public/favicon-32x32.png | Bin 0 -> 995 bytes website/public/favicon.svg | 5 + website/public/robots.txt | 4 + website/public/site.webmanifest | 20 +++ website/public/sitemap.xml | 8 ++ website/styles.css | 41 ++++-- 17 files changed, 1145 insertions(+), 31 deletions(-) create mode 100644 website/de/datenschutz/index.html create mode 100644 website/de/impressum/index.html create mode 100644 website/impressum/index.html create mode 100644 website/legal.css create mode 100644 website/privacy/index.html create mode 100644 website/public/apple-touch-icon.png create mode 100644 website/public/favicon-32x32.png create mode 100644 website/public/favicon.svg create mode 100644 website/public/robots.txt create mode 100644 website/public/site.webmanifest create mode 100644 website/public/sitemap.xml diff --git a/scripts/verify-website.mjs b/scripts/verify-website.mjs index 23f55f1..7256750 100644 --- a/scripts/verify-website.mjs +++ b/scripts/verify-website.mjs @@ -1,9 +1,40 @@ import { access, readFile } from 'node:fs/promises'; -const html = await readFile( - new URL('../website/dist/index.html', import.meta.url), - 'utf8', -); +const distUrl = new URL('../website/dist/', import.meta.url); +const pages = new Map([ + [ + 'privacy/index.html', + ['Privacy Policy', 'Vercel Inc.', 'no non-essential cookies'], + ], + [ + 'impressum/index.html', + ['Impressum', 'NIPE Solutions e.U.', 'ATU78464412'], + ], + [ + 'de/datenschutz/index.html', + ['Datenschutzerklärung', 'Vercel Inc.', 'Datenschutzbehörde'], + ], + [ + 'de/impressum/index.html', + ['Impressum', 'NIPE Solutions e.U.', 'FN 585066t'], + ], +]); +const pageHtml = new Map([ + ['index.html', await readFile(new URL('index.html', distUrl), 'utf8')], +]); + +for (const [path, expectedContent] of pages) { + const html = await readFile(new URL(path, distUrl), 'utf8'); + pageHtml.set(path, html); + for (const content of expectedContent) { + if (!html.includes(content)) + throw new Error(`${path} is missing defining content: ${content}`); + } +} + +const home = pageHtml.get('index.html'); +if (home === undefined) throw new Error('Missing built home page'); + for (const heading of [ 'Ownership model', 'Supported types', @@ -12,10 +43,70 @@ for (const heading of [ 'Migration from ImmuView v1', 'Security and trust model', ]) { - if (!html.includes(heading)) + if (!home.includes(heading)) throw new Error('Missing website section: ' + heading); } -if (html.includes('react')) + +for (const route of pages.keys()) { + const publicRoute = `/${route.replace('index.html', '')}`; + if (!home.includes(`href="${publicRoute}"`)) + throw new Error('Home page does not link legal route: ' + publicRoute); +} + +for (const example of [ + 'Nested protection', + 'Owner-side live updates', + 'Arrays', + 'Map and Set', + 'Date', + 'Circular references', + 'Shared identity', + 'Mutation rejection', +]) { + if (!home.includes(example)) + throw new Error('Missing website example: ' + example); +} + +const iconAssets = [ + '/favicon.svg', + '/favicon-32x32.png', + '/apple-touch-icon.png', + '/site.webmanifest', +]; +for (const [path, html] of pageHtml) { + if (html.includes('v2 alpha')) + throw new Error(`${path} unexpectedly contains v2 alpha`); + for (const asset of iconAssets) { + if (!html.includes(asset)) + throw new Error(`${path} does not link ${asset}`); + } +} +for (const asset of iconAssets) { + await access(new URL(asset.slice(1), distUrl)); +} + +const origin = 'https://readonly-view.nipesolutions.com'; +const canonicalUrls = [ + `${origin}/`, + ...[...pages.keys()].map( + (path) => `${origin}/${path.replace('index.html', '')}`, + ), +]; +for (const url of canonicalUrls) { + if (![...pageHtml.values()].some((html) => html.includes(url))) + throw new Error('Missing canonical page URL: ' + url); +} + +const robots = await readFile(new URL('robots.txt', distUrl), 'utf8'); +if (!robots.includes(`${origin}/sitemap.xml`)) + throw new Error('robots.txt does not link the production sitemap'); +const sitemap = await readFile(new URL('sitemap.xml', distUrl), 'utf8'); +for (const url of canonicalUrls) { + if (!sitemap.includes(`${url}`)) + throw new Error('Sitemap is missing: ' + url); +} + +if (home.includes('react')) throw new Error('Website unexpectedly references React'); -await access(new URL('../website/dist/assets', import.meta.url)); +await access(new URL('assets', distUrl)); console.log('Website structure verified'); diff --git a/test/browser/website.spec.ts b/test/browser/website.spec.ts index 49ef3f3..7a3c865 100644 --- a/test/browser/website.spec.ts +++ b/test/browser/website.spec.ts @@ -27,3 +27,29 @@ test('documentation has no narrow-screen overflow', async ({ page }) => { })); expect(widths.body).toBeLessThanOrEqual(widths.viewport); }); + +const legalRoutes = [ + ['/website/privacy/', 'Privacy Policy', 'Deutsch'], + ['/website/impressum/', 'Impressum', 'Deutsch'], + ['/website/de/datenschutz/', 'Datenschutzerklärung', 'English'], + ['/website/de/impressum/', 'Impressum', 'English'], +] as const; + +for (const [route, heading, language] of legalRoutes) { + test(`${route} has legal navigation and no horizontal overflow`, async ({ + page, + }) => { + await page.setViewportSize({ width: 390, height: 844 }); + await page.goto(route); + await expect( + page.getByRole('heading', { level: 1, name: heading }), + ).toBeVisible(); + await expect(page.getByRole('link', { name: language })).toBeVisible(); + await expect(page.getByRole('contentinfo')).toBeVisible(); + expect( + await page.evaluate(() => document.body.scrollWidth), + ).toBeLessThanOrEqual( + await page.evaluate(() => document.documentElement.clientWidth), + ); + }); +} diff --git a/test/integration/docs-examples.test.ts b/test/integration/docs-examples.test.ts index 338a575..4333506 100644 --- a/test/integration/docs-examples.test.ts +++ b/test/integration/docs-examples.test.ts @@ -16,3 +16,64 @@ it('matches the primary ownership example', () => { source.user.roles.push('editor'); expect(view.user).toEqual({ name: 'Bob', roles: ['admin', 'editor'] }); }); + +it('keeps array, Map, Set, and Date reads live while rejecting writes', () => { + const source = { + items: [{ id: 1 }], + map: new Map([['selected', { id: 1 }]]), + set: new Set([{ id: 1 }]), + updatedAt: new Date('2026-09-03T00:00:00.000Z'), + }; + const view = readonlyView(source); + + source.items.push({ id: 2 }); + source.map.set('next', { id: 2 }); + source.set.add({ id: 2 }); + source.updatedAt.setUTCDate(4); + + expect(view.items.map((item) => item.id)).toEqual([1, 2]); + expect(view.map.get('next')?.id).toBe(2); + expect([...view.set].map((item) => item.id)).toEqual([1, 2]); + expect(view.updatedAt.toISOString()).toBe('2026-09-04T00:00:00.000Z'); + expect(() => (view.items as { id: number }[]).push({ id: 3 })).toThrow( + DirectMutationError, + ); + expect(() => (view.map as Map).clear()).toThrow( + DirectMutationError, + ); + expect(() => (view.set as Set<{ id: number }>).clear()).toThrow( + DirectMutationError, + ); + expect(() => (view.updatedAt as Date).setUTCDate(5)).toThrow( + DirectMutationError, + ); +}); + +it('preserves cycles in a readonly view', () => { + type Node = { label: string; self?: Node }; + const source: Node = { label: 'root' }; + source.self = source; + + const view = readonlyView(source); + + expect(view.self).toBe(view); + expect(() => Reflect.set(view.self!, 'label', 'changed')).toThrow( + DirectMutationError, + ); +}); + +it('preserves shared identity across objects and collections', () => { + const shared = { id: 1 }; + const source = { + items: [shared], + map: new Map([['selected', shared]]), + set: new Set([shared]), + }; + const view = readonlyView(source); + + expect(view.items[0]).toBe(view.map.get('selected')); + expect([...view.set][0]).toBe(view.items[0]); + expect(() => Reflect.set(view.items[0]!, 'id', 2)).toThrow( + DirectMutationError, + ); +}); diff --git a/vite.website.config.ts b/vite.website.config.ts index 725aa28..681adfc 100644 --- a/vite.website.config.ts +++ b/vite.website.config.ts @@ -1,7 +1,32 @@ import { defineConfig } from 'vite'; +import { resolve } from 'node:path'; export default defineConfig({ root: 'website', - base: './', - build: { outDir: 'dist', emptyOutDir: true }, + base: '/', + build: { + outDir: 'dist', + emptyOutDir: true, + rollupOptions: { + input: { + index: resolve(import.meta.dirname, 'website/index.html'), + privacy: resolve( + import.meta.dirname, + 'website/privacy/index.html', + ), + impressum: resolve( + import.meta.dirname, + 'website/impressum/index.html', + ), + datenschutz: resolve( + import.meta.dirname, + 'website/de/datenschutz/index.html', + ), + 'de-impressum': resolve( + import.meta.dirname, + 'website/de/impressum/index.html', + ), + }, + }, + }, }); diff --git a/website/de/datenschutz/index.html b/website/de/datenschutz/index.html new file mode 100644 index 0000000..4410f80 --- /dev/null +++ b/website/de/datenschutz/index.html @@ -0,0 +1,181 @@ + + + + + + + + + + + Datenschutzerklärung — ReadonlyView + + + + + + + + + + +
+ RReadonlyView + NIPE primitives / 01 + +
+
+
+

Rechtliches / Datenschutz

+

Datenschutzerklärung

+

+ Diese Erklärung beschreibt die begrenzte Verarbeitung, die + für Bereitstellung und Schutz dieser statischen + Dokumentationswebsite erforderlich ist. +

+ English +
+
+
+
+

Verantwortlicher

+

+ Verantwortlicher ist NIPE Solutions e.U., + Achtergasse 10, 1230 Wien, Österreich. Kontakt: + office@nipesolutions.com. +

+
+
+

Bereitstellung und Sicherheit

+

+ Beim Abruf können technisch erforderliche Angaben + wie URL, Zeitpunkt, IP-Adresse, Browserinformationen + und Antwortstatus in Server- und + Sicherheitsprotokollen verarbeitet werden. Zweck + sind sichere Auslieferung, Fehleranalyse und + Missbrauchsschutz. Rechtsgrundlage ist das + berechtigte Interesse am sicheren und zuverlässigen + Betrieb gemäß Art. 6 Abs. 1 lit. f DSGVO. +

+
+
+

Hosting und Empfänger

+

+ Hosting-Anbieter ist Vercel Inc. Vercel und dessen + Unterauftragsverarbeiter können Anfragedaten unter + den jeweils anwendbaren Garantien außerhalb des EWR + verarbeiten. Details stehen in der + Datenschutzerklärung von Vercel + und im + Auftragsverarbeitungsnachtrag. +

+
+
+

Cookies und Analyse

+

+ Diese Projektwebsite setzt bewusst keine nicht + erforderlichen Cookies ein und verwendet keinen + Produktanalysedienst. Für externe Ziele wie GitHub + und npm gelten nach dem Aufruf deren eigene + Datenschutzbestimmungen. +

+
+
+

Kontakt und Speicherdauer

+

+ Bei einer Kontaktaufnahme per E-Mail werden die + übermittelten Daten zur Bearbeitung der Anfrage und + nur so lange gespeichert, wie dies dafür oder + aufgrund gesetzlicher Pflichten erforderlich ist. + Rechtsgrundlage ist Art. 6 Abs. 1 lit. b DSGVO, + soweit die Anfrage einen Vertrag oder + vorvertragliche Maßnahmen betrifft, andernfalls Art. + 6 Abs. 1 lit. f DSGVO—das berechtigte Interesse an + der Beantwortung von Projekt- und + Geschäftskorrespondenz. Ein E-Mail-Dienstleister + kann die Nachricht im Auftrag und, soweit + erforderlich, unter geeigneten Garantien für + internationale Übermittlungen verarbeiten. + Betriebsprotokolle werden nach den konfigurierten + Sicherheits- und Servicefristen des + Hosting-Anbieters begrenzt. +

+
+
+

Ihre Rechte

+

+ Unter den Voraussetzungen der DSGVO bestehen + insbesondere Rechte auf Auskunft, Berichtigung, + Löschung, Einschränkung, Datenübertragbarkeit und + Widerspruch. Beschwerden können an die + Österreichische Datenschutzbehörde + gerichtet werden. Zur Ausübung eines Rechts + kontaktieren Sie den Verantwortlichen. +

+
+
+ +
+
+ + + diff --git a/website/de/impressum/index.html b/website/de/impressum/index.html new file mode 100644 index 0000000..6e46fe8 --- /dev/null +++ b/website/de/impressum/index.html @@ -0,0 +1,140 @@ + + + + + + + + + + + Impressum — ReadonlyView + + + + + + + + + + +
+ RReadonlyView + NIPE primitives / 01 + +
+
+
+

Rechtliches / Anbieterinformation

+

Impressum

+

+ Anbieterkennzeichnung, Offenlegung und Medieninhaber der + Website und des Open-Source-Projekts ReadonlyView. +

+ English +
+
+
+
+

Diensteanbieter, Medieninhaber und Herausgeber

+

+ NIPE Solutions e.U.
Inhaber: + Nicholas Petrasek
Achtergasse 10
1230 + Wien, Österreich +

+

+ E-Mail: + office@nipesolutions.com
Telefon: + +43 676 9654266 +

+
+
+

Unternehmensdaten

+

+ UID-Nummer: ATU78464412
Firmenbuchnummer: + FN 585066t
Firmenbuchgericht: + Handelsgericht Wien
Firmensitz: Wien +

+
+
+

Gewerbe und Aufsicht

+

+ Gewerbe: Dienstleistungen in der automatischen + Datenverarbeitung und Informationstechnik. + Aufsichts- und Gewerbebehörde: Magistratisches + Bezirksamt für den 23. Bezirk. Mitglied der + Wirtschaftskammer Wien. Anwendbare Rechtsvorschrift + ist die Gewerbeordnung, abrufbar im + Rechtsinformationssystem des Bundes. +

+
+
+

Blattlinie

+

+ Technische Dokumentation, Beispiele und + Projektinformationen zur Open-Source-Bibliothek + ReadonlyView. Medieninhaber und verantwortlich für + den Inhalt: NIPE Solutions e.U., Achtergasse 10, + 1230 Wien. +

+
+
+ +
+
+ + + diff --git a/website/impressum/index.html b/website/impressum/index.html new file mode 100644 index 0000000..13dd3a1 --- /dev/null +++ b/website/impressum/index.html @@ -0,0 +1,151 @@ + + + + + + + + + + + Impressum — ReadonlyView + + + + + + + + + + +
+ RReadonlyView + NIPE primitives / 01 + +
+
+
+

Legal / Provider information

+

Impressum

+

+ Provider, media-owner, and publisher information for the + ReadonlyView project and documentation website. +

+ Deutsch +
+
+
+
+

Service provider, media owner, and publisher

+

+ NIPE Solutions e.U.
Proprietor: Nicholas Petrasek
Achtergasse + 10
1230 Wien, Austria +

+

+ Email: + office@nipesolutions.com
Phone: + +43 676 9654266 +

+
+
+

Company information

+

+ VAT ID: ATU78464412
Company register number: FN + 585066t
Company register court: Handelsgericht + Wien
Registered office: Wien +

+
+
+

Trade and supervision

+

+ Trade: Dienstleistungen in der automatischen + Datenverarbeitung und Informationstechnik. +

+

+ Supervisory and trade authority: Magistratisches + Bezirksamt für den 23. Bezirk. Chamber membership: + Wirtschaftskammer Wien. Applicable trade law is the + Austrian Trade Regulation Act (GewO), available + through the + Austrian Legal Information System. +

+
+
+

Editorial direction

+

+ Technical documentation, examples, and project + information for the open-source ReadonlyView + library. Media owner and editorial responsibility: + NIPE Solutions e.U., Achtergasse 10, 1230 Wien. +

+
+
+

Project and external links

+

+ The software is provided under the MIT License. + Links to external websites, including GitHub and + npm, lead to services operated under their + respective providers’ terms and privacy information. +

+
+
+ +
+
+ + + diff --git a/website/index.html b/website/index.html index c549774..8a5c774 100644 --- a/website/index.html +++ b/website/index.html @@ -9,13 +9,35 @@ /> + - + + ReadonlyView — a live readonly membrane + + + + + @@ -34,9 +56,6 @@
-

- v2 alpha · zero runtime dependencies -

The source stays mutable.
The view does not.

A deeply readonly, lazy, live view over mutable @@ -88,8 +107,11 @@

The source stays mutable.
The view does not.

>Every supported exposure route is wrapped.
- Small1.9 kB minified + gzip baseline. + v2Zero runtime dependencies. 1.9 kB minified + gzip + baseline.
@@ -98,6 +120,7 @@

The source stays mutable.
The view does not.

diff --git a/website/legal.css b/website/legal.css new file mode 100644 index 0000000..3307db5 --- /dev/null +++ b/website/legal.css @@ -0,0 +1,106 @@ +.legal-shell { + width: min(1120px, calc(100% - 80px)); + margin: 0 auto; + padding: 88px 0 104px; +} +.legal-header { + max-width: 760px; + padding-bottom: 56px; + border-bottom: 1px solid var(--rule); +} +.legal-header h1 { + margin: 18px 0 24px; + font-size: clamp(48px, 7vw, 76px); +} +.legal-kicker { + margin: 0; + color: var(--blue); + font-size: 14px; + font-weight: 650; +} +.legal-intro { + margin: 0; + max-width: 65ch; + color: #4c5158; + font-size: 19px; + line-height: 1.65; +} +.legal-content { + display: grid; + grid-template-columns: minmax(0, 720px) minmax(220px, 1fr); + gap: 88px; + padding-top: 64px; +} +.legal-content article { + min-width: 0; +} +.legal-content section + section { + margin-top: 52px; + padding-top: 52px; + border-top: 1px solid var(--rule); +} +.legal-content h2 { + margin: 0 0 18px; + font-size: 27px; + letter-spacing: -0.025em; +} +.legal-content p, +.legal-content li { + max-width: 72ch; + color: #444950; + font-size: 17px; + line-height: 1.75; +} +.legal-content a, +.legal-meta a { + color: #173c91; + text-decoration: underline; + text-decoration-color: #9db7ff; + text-underline-offset: 3px; +} +.legal-meta { + align-self: start; + position: sticky; + top: 104px; + padding-left: 22px; + border-left: 3px solid var(--blue); + color: var(--muted); + font-size: 14px; + line-height: 1.65; +} +.legal-meta p { + margin: 0 0 20px; +} +.legal-meta strong { + color: var(--ink); +} +.language-switch { + display: inline-flex; + margin-top: 22px; +} + +@media (max-width: 720px) { + .legal-shell { + width: min(100% - 40px, 720px); + padding: 56px 0 72px; + } + .legal-header { + padding-bottom: 40px; + } + .legal-header h1 { + font-size: clamp(42px, 14vw, 60px); + } + .legal-content { + grid-template-columns: 1fr; + gap: 56px; + padding-top: 48px; + } + .legal-content section + section { + margin-top: 40px; + padding-top: 40px; + } + .legal-meta { + position: static; + order: -1; + } +} diff --git a/website/privacy/index.html b/website/privacy/index.html new file mode 100644 index 0000000..45e4af4 --- /dev/null +++ b/website/privacy/index.html @@ -0,0 +1,174 @@ + + + + + + + + + + + Privacy Policy — ReadonlyView + + + + + + + + + + +
+ RReadonlyView + NIPE primitives / 01 + +
+
+
+

Legal / Data protection

+

Privacy Policy

+

+ This notice describes the limited processing required to + deliver and protect this static documentation website. +

+ Deutsch +
+
+
+
+

Controller

+

+ The controller is NIPE Solutions e.U., Achtergasse + 10, 1230 Wien, Austria. Contact: + office@nipesolutions.com. +

+
+
+

Website delivery and security

+

+ When you request a page, technically necessary + information such as the requested URL, timestamp, IP + address, browser information, and response status + may be processed in server and security logs. This + supports reliable delivery, fault diagnosis, and + protection against abuse. The legal basis is the + controller’s legitimate interest in secure and + reliable operation under Article 6(1)(f) GDPR. +

+
+
+

Hosting and recipients

+

+ The website is hosted by Vercel Inc. Vercel and its + subprocessors may process request data outside the + European Economic Area under applicable transfer + safeguards. Current provider details are available + in the + Vercel privacy policy + and + data processing addendum. +

+
+
+

Cookies and analytics

+

+ There are no non-essential cookies intentionally set + by this project website, and it does not run a + product analytics service. External destinations + such as GitHub and npm apply their own privacy terms + after you follow a link to them. +

+
+
+

Contact and retention

+

+ If you contact the operator by email, the supplied + contact and message data is processed to answer your + request and retained only as long as needed for that + purpose or applicable legal obligations. The legal + basis is Article 6(1)(b) GDPR where the request + concerns a contract or steps before a contract, and + otherwise Article 6(1)(f) GDPR—the legitimate + interest in answering project and business + correspondence. An email service provider may + process the message on the controller’s behalf and, + where applicable, under appropriate international + transfer safeguards. Operational log retention is + limited by the hosting provider’s configured service + and security requirements. +

+
+
+

Your rights

+

+ Subject to the GDPR’s conditions, you may request + access, rectification, erasure, restriction, + portability, or object to processing. You may + complain to the + Austrian Data Protection Authority. Contact the controller to exercise a right. +

+
+
+ +
+
+ + + diff --git a/website/public/apple-touch-icon.png b/website/public/apple-touch-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..c212ec10ff9124cd3f126744724154d27703a752 GIT binary patch literal 5214 zcmYLN1yq#X)*gl)8s?)zX&GP$r5i@N5oAC>Mqos`yPE+dq+^iy2qlzIx@3?BDQS>y zq)YC2@A}uj-u0f^>+HSPj%S~9V)b-X$v})C002OyuBKvu?d$&jL1RW`29BN`pBo{x(X{)C1 zcUe&x@9F_>49+V`Jo5uy!6FoT?-NnXCxTH|Ul;tR<^WhVG6VorBGPMd-;r}&iTQzFB9UqEwbL%9a&IqA=LKi{= z|2v%6+-|{n6?abFa}@VrdS(xJi2T_P1_v)8TF+qC&EhS&(%!4g_cuoV_GFra(l(ls z_Yv0am%(QJI8gdwppNnVQ*{Kbyp_=!A7lIiyVs{|?7HPt!up&SR zWc(z~iIiUu*WTKFCIuRj4kzL&2cXJ>PeVZf>5dt0f;OF#V_nTSS-UQYmxlaw$c#$U z25XY}Ude0RFGL{%&MDdO58>_R#hL0c> znMY7iTTn&CwIIQ{M2Ky2F3FYb|%anMmw)N9smZS58 z7yM%F5g!!M@liU%PmbiQMTrHOelX04QxgmrRg$447A@uCC|r1s)NYDNyJ7e>a^SGw z1k8W+v~L4k(R+1ub-gVr4<*T z$or4LQEBj9?Aey&9o5pcVvI^$XtgN#=B$~nu_8^DVms8Ud4YkzWICiUb#Jj}cF#2M zt)38w=#LE*>5TPdeNc0}*|WY}<ItmFk(d1|8ax+zJ2sK<>Ycy^mf@9K7I#FD_cxS>`P{X9&ItFby>xPbz=|m-*E1)WDSs zHv}z&OSBd1Rtw2H{`(oKQ)E2rTxbvPDIY-ht5f#c&fwKIGX~O1u_S+NadC&8-8yS` zXygYk-xvN8yL676TR64Gy)_(lxBbl&cM$e@z(GjBw0ORnx4%GxjxJykEzI?p zE=BY*znju~V)Q=m;{(i#=WXeG$EO<8#gI6v;Xsy6(Na+~Oxf@4%!YIu!=f@6`VRn(BgsLZYNpk>8-1JXVW$6Sv#Z-gNW|5z=_Nv zT5i*rILLy+hrv!-yE2!%eha-*kWq$zcvJyMvx1S7-twvdGT<|5*nsT6mDF)NqKVrI zc6N3=xAz(}NQQ<$7 z_)=sv?+Jle|K5X$+pwa8e@j*;NfENR8a?8aVc!*+Mf#mL6x>A%90IJB z+gjvU?*#f8hT5VQY)bRrF0J5Pk_WR}3}3R?&XN$$uG^=Rp`)`lB61ThYA%&rddH-_ z71T?StuE+)%$B`I6Q8PtDV*sN<^JS?SIs)c9qHh7g>EoU$4^mHqYk$SR^a4|mUYIw zqk!X{9XRt#EU-Ai1a;CB1TUGAX)!zAHgS|imX z5aSlsyN^eODLL_g@;RV7vsVM*XpC%+Zvs$q*R^|dn^@PnZ~2BpHUZ5CsiYJFmdOM% zVv-6vI)A&Ry<_RgZ}mUAn>svJ{x0UzO0@)*e+8Vh0f?)J84?1J_2*&$vAjxdB$_O0 zo_D}~LQTUB2rw`-7<~^T@z|L-ZvWFfvWcPKlDFEQJ-a;WPC8nc`Y42YyYEgP^pxex zAvjZ3yDaw+KZPQY<+M7g%QR(XFUBF;RvAOia&%Ode7Ssgan!yPkf4f5f}L#Co&;sC zh`am2j`#`Mry%pMtyQR%va*~|0Z2SC=Ue9ZrRNdkk&(&y2Hp5tc-b6CT9}gs?3yq{CuP0Q z!?yZK6B>JJ#2y7?L5z=&*92S{oNg~jh=-LZU>-D=u1uP2iuLOmq7i8?eh4`q?9KSp z*#YsTqOiQLPBy#N?PaQ0_0R}&ogbx{QtKsZx*QI?qX`Pt`LZs`_r0~8X}|?FnUhn) zdtU~=bbT}vamGO8%^z#O$}eR!f$fllkWb-+R7W=@XYLZrE>d|lbJ~t`Q&!4Rq`mXL zC;HEx{WIm-9Sam#ZrXM33B@fnHX$1GWYNyCEvgCh2RAq;<+u8wwRfk+F;|TfY2bO8 zW$qTKV8y=Pn8!`)G3cfyslA_{>73inbY&!0UVAjZm%e@xD3D&wOR%X#xS#2DG9(^Z zT>VTBEnqv4?kp70qjr0B%~bQ|!fE?X+G{Js`08r>29A$E`(Dg(7S(oF)hWId0BQA3 zVy$f+0^!egRa8{C415f)3A`aM4}`Ygij?1dhyXge{;O+Zeae9-Sv0hquZPgb50#97 zw|I{xO)L>-InL_48M(O;gIbMsLB>jb{ZDyU;|Drh9u5gpe`GrOu9MV1wFgx5G^6Z2h|)=OMDiX~FNWp=iIu z^=wO-Xe@nL18+{#7jKSMIA-duAlrc-!+?%dC}EHNaeVJZSEj1gbH=SE))dz`ld1^I z)pSy0Zqr>Cb6a*elKS^!3arT?t=7mt!T zdJuG3$T@BpOOFj)oKOY82_3&mb>+3#ju5U#WTGFFxKr0J-CHuV_ItT;!&*F$N80u3 z095#@&}ckK|RGrgT9_#$Yy?^)cB7YnWlA07fhb_FRUj@<*-0xJDeGnE-;cR zmNZAO5C;`^>WTZu&HE&Y3yj2>Yd9>MR{umnD$wPB*h$6T+>X&0lY4ZqB?hltmWZ{jlEo16m<^CawI(@fDq=#{SPw>%N(%t19KP z2z-309@1_F{V|tZsX(~>(w}L|=s9O5&U!n3>=wnVLS>)RF-*zD-HrRmau~^Q#-ez( zKDztWdd1}P`fKfSSm9#SRe3AW%ZAx3GZfY$u6p-cV zyLZogTxN*2+uPa>My6L6{SVS-Md4UZ4nInVGUX7Zr)@O(*G!<_0#MCa{SHEs3e+5eI{4lfYMF`-;Z_owztxw*_*Ib!%I;qt&DVtgs3^Mi$G zo`RJ7Px^ zFy{s&BC^IZ|JnwOBzc4ldH3L83%?~4igYkrlBJ?TCz3zGn)Xt+BeW@atG6OjmGj~8_<-T@w+y$7b3h2TVhrZVl4R3Frk2sI5!uEm@kxj`#1os zyQs+rj(Nhagb|j;H^QXG1mE5G~Um5)Gkxe#E^S^t$17R*Oyp* zVygF2W?jBx4l8~I78y;>FENIj6~um#Rs0ZXoaM};vIruBUpZNiO(ULkkmlM^!~=dhhStztdiQA{FBCGhCo7M6t2eDv6`&3AV)bu<>ZqMTIsvG<+r-3fSndR z1?*^xI(<;9{bqb}5NbeP#`tD5U55;Gx_x(}%cn;Ww%EgASGcvUh7_j-Lhb+^b}nKr znD-52@Pp}PmYa%72nDxPo&}(laW=k(ytK>(EJwnn=;LNFQv-xisw%B@pN~94 z7q7f^Tpxomy|oQ7w_;Nk}jEb|Oio_Df4MTDyp_?_*PCe4ZTZcDvw5SxHsm!Am->QEV@pfR zQ=48-Kttc2=KFBjX0}zcBudD}9t7XMJ;i#2A%l(r#rwPCKZs;cwJI%FGrZE3?3z;Q_{=d}?2@yB?|3~!!@ zsw5P2>@GlI`%_rLSeEGy2GSeL1^V{K3q}q`T2A}hx^8KGMEk!Xl2?nZG|=L z{&tT_0$U~j(EnV~23;R`m7s91;pgYaZFjDywQ|=v_KyPnh#E3CQ-I3e{^1^jNmqW5 zBzkL;?*eD0Pjc~;@X|murz0YK9eDS~sZn}ND9tIimX&l16a@q@B>9fQYpC={rpVt%tmdLGW>>M2bf{Dkk9<>?|^awW>mpE+t&XJVushdRlK2mk*ThaJ7`UA+e+E9sl1puO<14~77Bn2t)7 Il2zD$0DBVirvLx| literal 0 HcmV?d00001 diff --git a/website/public/favicon-32x32.png b/website/public/favicon-32x32.png new file mode 100644 index 0000000000000000000000000000000000000000..570c11236994a96f8f5db48815bd106a85d403c5 GIT binary patch literal 995 zcmV<9104K`P)bf;mk6OCPtr3M99R%j74Tl92+x=Z`;cf-asgYz*_+$5D1L+-X0%p zFHF)=C`G@?%{}M*&iQ>m=lsr1F8s$5nF79Gu-Fy1!!k)waT$f`-ipJD?kz$n%4SKW zaM_Ay--2#74XYkAV!7kLO?KDLX9ZxIreC67mhc*&Z)GmxfpK%ahrH++7ZUVDUi+4p6a0u0I8kd+iCOl5QPn2fnGF) zr8lHc!l`HK*z;lzAn#AJGSQ8IGNC6fIbe{waI4ldIo5nL387JV^hbnd#BHme-R6QOB&;UeI9+VkBNI2j6KIdCoGR7Ad7l}m1=(~A~Z@a%^ zd3ibGT>E|u9T1X3kiG*7d$+oq_40bX)YsQ>@uLe2{Q3)}B_)|B+bjRPMbf(lu!AZu z57E`xfe;Tl(skMvfIm>;JO@h4cbK1H~Cv+%;Y5Ld9 zM@G1F=WhN08XJ#hjLpol%ZDgT!LfTgtU9fS+&l0dS-5CKVNj2_HKKz?WZq&d|^>W6@~VxpFFj zl#+8Tt<25M0bm#gU7a0xJf7VF0Eoq=Ios0e^sA~KrTy}yhpgCP0D%7f+g$Bg`!ruU zd4iW;I-Wg1GAR~wh4|pZHpa&%oc?E@enMqs<%W4eGe~(ZK3n=z^{#FYZ`8zIyaV^^yl*kHyVx8mZE zPuEw%NuiVp#S_%LWo1$^e2V7Yv#GJ}Th`ox1=S4SQ}>vocEUA~uKE8?e*-+U8Wl&L R_EG=<002ovPDHLkV1g8m+Ohxu literal 0 HcmV?d00001 diff --git a/website/public/favicon.svg b/website/public/favicon.svg new file mode 100644 index 0000000..60bab55 --- /dev/null +++ b/website/public/favicon.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/website/public/robots.txt b/website/public/robots.txt new file mode 100644 index 0000000..4f04212 --- /dev/null +++ b/website/public/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://readonly-view.nipesolutions.com/sitemap.xml diff --git a/website/public/site.webmanifest b/website/public/site.webmanifest new file mode 100644 index 0000000..99225eb --- /dev/null +++ b/website/public/site.webmanifest @@ -0,0 +1,20 @@ +{ + "name": "ReadonlyView", + "short_name": "ReadonlyView", + "description": "A deeply readonly, lazy, live view over mutable JavaScript data.", + "icons": [ + { + "src": "/favicon-32x32.png", + "sizes": "32x32", + "type": "image/png" + }, + { + "src": "/apple-touch-icon.png", + "sizes": "180x180", + "type": "image/png" + } + ], + "theme_color": "#15171a", + "background_color": "#f7f8f6", + "display": "standalone" +} diff --git a/website/public/sitemap.xml b/website/public/sitemap.xml new file mode 100644 index 0000000..1eec868 --- /dev/null +++ b/website/public/sitemap.xml @@ -0,0 +1,8 @@ + + + https://readonly-view.nipesolutions.com/ + https://readonly-view.nipesolutions.com/privacy/ + https://readonly-view.nipesolutions.com/impressum/ + https://readonly-view.nipesolutions.com/de/datenschutz/ + https://readonly-view.nipesolutions.com/de/impressum/ + diff --git a/website/styles.css b/website/styles.css index ecbce17..5a7a8e2 100644 --- a/website/styles.css +++ b/website/styles.css @@ -78,19 +78,6 @@ button { gap: 72px; align-items: center; } -.status { - font-size: 13px; - color: var(--muted); - display: flex; - align-items: center; - gap: 8px; -} -.status span { - width: 8px; - height: 8px; - border-radius: 50%; - background: var(--success); -} h1 { font-size: clamp(46px, 6vw, 82px); line-height: 0.98; @@ -241,6 +228,11 @@ code { letter-spacing: -0.03em; margin: 0 0 22px; } +.content h3 { + font-size: 18px; + letter-spacing: -0.015em; + margin: 0; +} .content p, .content li, .content dd { @@ -256,6 +248,19 @@ code { border-radius: 9px; overflow: auto; } +.example-grid { + display: grid; + gap: 28px; + margin-top: 36px; +} +.example { + display: grid; + gap: 12px; + min-width: 0; +} +.example pre { + margin: 0; +} .content code { font-size: 0.88em; } @@ -329,6 +334,12 @@ footer { color: var(--muted); font-size: 13px; } +footer nav { + display: flex; + flex-wrap: wrap; + justify-content: flex-end; + gap: 10px 22px; +} :focus-visible { outline: 3px solid var(--blue); outline-offset: 3px; @@ -406,6 +417,10 @@ footer { display: grid; gap: 8px; } + footer nav { + display: grid; + justify-content: start; + } } @media (prefers-reduced-motion: reduce) { html { From e3afd4fb2e7dd77de1cd232f06f1effa4ee1d4bf Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:26:28 +0200 Subject: [PATCH 03/14] fix(website): verify production legal routes --- playwright.config.ts | 18 ++++-- scripts/verify-website.mjs | 78 +++++++++++++++++++++++--- test/browser/website.spec.ts | 70 +++++++++++++++-------- test/integration/docs-examples.test.ts | 28 +++++++++ website/de/datenschutz/index.html | 2 +- website/index.html | 30 ++++++++-- website/legal.css | 4 +- website/styles.css | 4 ++ 8 files changed, 190 insertions(+), 44 deletions(-) diff --git a/playwright.config.ts b/playwright.config.ts index 9c31d33..c7e3a0c 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -16,9 +16,17 @@ export default defineConfig({ reporter: process.env.CI ? [['html', { open: 'never' }], ['line']] : 'line', use: { baseURL: 'http://127.0.0.1:4173', trace: 'on-first-retry' }, projects, - webServer: { - command: 'npm run build:dist && vite --host 127.0.0.1 --port 4173', - port: 4173, - reuseExistingServer: !process.env.CI, - }, + webServer: [ + { + command: 'vite --host 127.0.0.1 --port 4173 --strictPort', + port: 4173, + reuseExistingServer: !process.env.CI, + }, + { + command: + 'npm run build:website && vite preview --config vite.website.config.ts --host 127.0.0.1 --port 42873 --strictPort', + port: 42873, + reuseExistingServer: !process.env.CI, + }, + ], }); diff --git a/scripts/verify-website.mjs b/scripts/verify-website.mjs index 7256750..bda7892 100644 --- a/scripts/verify-website.mjs +++ b/scripts/verify-website.mjs @@ -67,6 +67,42 @@ for (const example of [ throw new Error('Missing website example: ' + example); } +function exampleCard(heading) { + const marker = `

${heading}

`; + const start = home.indexOf(marker); + const end = home.indexOf('', start); + if (start < 0 || end < 0) + throw new Error('Missing website example card: ' + heading); + return home.slice(start, end); +} + +for (const [heading, expectedContent] of [ + [ + 'Owner-side live updates', + [ + "import { readonlyView } from '@nipe-solutions/readonly-view'", + 'const source =', + 'const view = readonlyView(source)', + ], + ], + [ + 'Mutation rejection', + [ + 'DirectMutationError', + "from '@nipe-solutions/readonly-view'", + 'const source =', + 'const view = readonlyView(source)', + 'error instanceof DirectMutationError', + ], + ], +]) { + const card = exampleCard(heading); + for (const content of expectedContent) { + if (!card.includes(content)) + throw new Error(`${heading} example is not standalone: ${content}`); + } +} + const iconAssets = [ '/favicon.svg', '/favicon-32x32.png', @@ -86,15 +122,39 @@ for (const asset of iconAssets) { } const origin = 'https://readonly-view.nipesolutions.com'; -const canonicalUrls = [ - `${origin}/`, - ...[...pages.keys()].map( - (path) => `${origin}/${path.replace('index.html', '')}`, - ), -]; -for (const url of canonicalUrls) { - if (![...pageHtml.values()].some((html) => html.includes(url))) - throw new Error('Missing canonical page URL: ' + url); +const canonicalUrls = []; +for (const [path, html] of pageHtml) { + const route = path === 'index.html' ? '' : path.replace('index.html', ''); + const expectedUrl = `${origin}/${route}`; + canonicalUrls.push(expectedUrl); + + const canonicalTags = (html.match(/]*>/g) ?? []).filter((tag) => + tag.includes('rel="canonical"'), + ); + if (canonicalTags.length !== 1) + throw new Error( + `${path} has ${canonicalTags.length} canonical tags; expected 1`, + ); + const canonicalTag = canonicalTags[0]; + const canonicalUrl = canonicalTag?.match(/href="([^"]+)"/)?.[1]; + if (canonicalUrl !== expectedUrl) + throw new Error( + `${path} canonical URL is ${canonicalUrl ?? 'missing'}; expected ${expectedUrl}`, + ); + + const openGraphTags = (html.match(/]*>/g) ?? []).filter((tag) => + tag.includes('property="og:url"'), + ); + if (openGraphTags.length !== 1) + throw new Error( + `${path} has ${openGraphTags.length} Open Graph URL tags; expected 1`, + ); + const openGraphTag = openGraphTags[0]; + const openGraphUrl = openGraphTag?.match(/content="([^"]+)"/)?.[1]; + if (openGraphUrl !== expectedUrl) + throw new Error( + `${path} Open Graph URL is ${openGraphUrl ?? 'missing'}; expected ${expectedUrl}`, + ); } const robots = await readFile(new URL('robots.txt', distUrl), 'utf8'); diff --git a/test/browser/website.spec.ts b/test/browser/website.spec.ts index 7a3c865..098cd73 100644 --- a/test/browser/website.spec.ts +++ b/test/browser/website.spec.ts @@ -1,7 +1,9 @@ import { expect, test } from '@playwright/test'; +const websiteOrigin = 'http://127.0.0.1:42873'; + test('documentation navigation and live demo work', async ({ page }) => { - await page.goto('/website/index.html'); + await page.goto(websiteOrigin + '/'); await expect( page.getByRole('heading', { name: 'The source stays mutable. The view does not.', @@ -20,7 +22,7 @@ test('documentation navigation and live demo work', async ({ page }) => { test('documentation has no narrow-screen overflow', async ({ page }) => { await page.setViewportSize({ width: 390, height: 844 }); - await page.goto('/website/index.html'); + await page.goto(websiteOrigin + '/'); const widths = await page.evaluate(() => ({ body: document.body.scrollWidth, viewport: document.documentElement.clientWidth, @@ -29,27 +31,51 @@ test('documentation has no narrow-screen overflow', async ({ page }) => { }); const legalRoutes = [ - ['/website/privacy/', 'Privacy Policy', 'Deutsch'], - ['/website/impressum/', 'Impressum', 'Deutsch'], - ['/website/de/datenschutz/', 'Datenschutzerklärung', 'English'], - ['/website/de/impressum/', 'Impressum', 'English'], + ['/privacy/', 'Privacy Policy', 'Deutsch'], + ['/impressum/', 'Impressum', 'Deutsch'], + ['/de/datenschutz/', 'Datenschutzerklärung', 'English'], + ['/de/impressum/', 'Impressum', 'English'], ] as const; for (const [route, heading, language] of legalRoutes) { - test(`${route} has legal navigation and no horizontal overflow`, async ({ - page, - }) => { - await page.setViewportSize({ width: 390, height: 844 }); - await page.goto(route); - await expect( - page.getByRole('heading', { level: 1, name: heading }), - ).toBeVisible(); - await expect(page.getByRole('link', { name: language })).toBeVisible(); - await expect(page.getByRole('contentinfo')).toBeVisible(); - expect( - await page.evaluate(() => document.body.scrollWidth), - ).toBeLessThanOrEqual( - await page.evaluate(() => document.documentElement.clientWidth), - ); - }); + for (const width of [390, 320]) { + test(`${route} loads styles and has no ${width}px overflow`, async ({ + page, + }) => { + const stylesheets: { status: number; url: string }[] = []; + const failedStylesheets: string[] = []; + page.on('response', (response) => { + if (response.request().resourceType() === 'stylesheet') { + stylesheets.push({ + status: response.status(), + url: response.url(), + }); + } + }); + page.on('requestfailed', (request) => { + if (request.resourceType() === 'stylesheet') { + failedStylesheets.push(request.url()); + } + }); + await page.setViewportSize({ width, height: 844 }); + await page.goto(websiteOrigin + route); + await expect( + page.getByRole('heading', { level: 1, name: heading }), + ).toBeVisible(); + await expect( + page.getByRole('link', { name: language }), + ).toBeVisible(); + await expect(page.getByRole('contentinfo')).toBeVisible(); + expect(failedStylesheets).toEqual([]); + expect(stylesheets).toHaveLength(2); + expect(stylesheets).toEqual( + stylesheets.map(({ url }) => ({ status: 200, url })), + ); + expect( + await page.evaluate(() => document.body.scrollWidth), + ).toBeLessThanOrEqual( + await page.evaluate(() => document.documentElement.clientWidth), + ); + }); + } } diff --git a/test/integration/docs-examples.test.ts b/test/integration/docs-examples.test.ts index 4333506..d3b1bd1 100644 --- a/test/integration/docs-examples.test.ts +++ b/test/integration/docs-examples.test.ts @@ -17,6 +17,34 @@ it('matches the primary ownership example', () => { expect(view.user).toEqual({ name: 'Bob', roles: ['admin', 'editor'] }); }); +it('matches the standalone owner-side live updates example', () => { + const source = { user: { name: 'Alice' } }; + const view = readonlyView(source); + + source.user.name = 'Bob'; + + expect(view.user.name).toBe('Bob'); +}); + +it('matches the standalone mutation rejection example', () => { + const source = { item: { id: 1 } }; + const view = readonlyView(source); + + let errorName: string | undefined; + try { + Reflect.set(view.item, 'id', 2); + } catch (error) { + if (error instanceof DirectMutationError) { + errorName = error.name; + } else { + throw error; + } + } + + expect(errorName).toBe('DirectMutationError'); + expect(source.item.id).toBe(1); +}); + it('keeps array, Map, Set, and Date reads live while rejecting writes', () => { const source = { items: [{ id: 1 }], diff --git a/website/de/datenschutz/index.html b/website/de/datenschutz/index.html index 4410f80..9c6e805 100644 --- a/website/de/datenschutz/index.html +++ b/website/de/datenschutz/index.html @@ -59,7 +59,7 @@

Rechtliches / Datenschutz

-

Datenschutzerklärung

+

Datenschutzerklärung

Diese Erklärung beschreibt die begrenzte Verarbeitung, die für Bereitstellung und Schutz dieser statischen diff --git a/website/index.html b/website/index.html index 8a5c774..cc8af07 100644 --- a/website/index.html +++ b/website/index.html @@ -160,7 +160,8 @@

Ownership model

Examples

Each example uses the public API and can be copied - into a modern JavaScript or TypeScript project. + into a modern JavaScript project. TypeScript rejects + the mutation lines before they reach runtime. 

import { readonlyView } from '@nipe-solutions/readonly-view'
@@ -173,8 +174,13 @@

Nested protection

Owner-side live updates

- 
source.user.name = 'Bob'
-view.user.name // 'Bob'
+ 
import { readonlyView } from '@nipe-solutions/readonly-view'
+
+const source = { user: { name: 'Alice' } }
+const view = readonlyView(source)
+
+source.user.name = 'Bob'
+console.log(view.user.name) // 'Bob'

Arrays

@@ -228,10 +234,22 @@

Shared identity

Mutation rejection

- 
try {
-  Reflect.set(view.items[0], 'id', 2)
+                                
import {
+  DirectMutationError,
+  readonlyView,
+} from '@nipe-solutions/readonly-view'
+
+const source = { item: { id: 1 } }
+const view = readonlyView(source)
+
+try {
+  Reflect.set(view.item, 'id', 2)
 } catch (error) {
-  error.name // 'DirectMutationError'
+  if (error instanceof DirectMutationError) {
+    console.log(error.name) // 'DirectMutationError'
+  } else {
+    throw error
+  }
 }
diff --git a/website/legal.css b/website/legal.css index 3307db5..ec032da 100644 --- a/website/legal.css +++ b/website/legal.css @@ -11,6 +11,8 @@ .legal-header h1 { margin: 18px 0 24px; font-size: clamp(48px, 7vw, 76px); + overflow-wrap: anywhere; + hyphens: auto; } .legal-kicker { margin: 0; @@ -88,7 +90,7 @@ padding-bottom: 40px; } .legal-header h1 { - font-size: clamp(42px, 14vw, 60px); + font-size: clamp(38px, 12vw, 52px); } .legal-content { grid-template-columns: 1fr; diff --git a/website/styles.css b/website/styles.css index 5a7a8e2..c6970bf 100644 --- a/website/styles.css +++ b/website/styles.css @@ -371,6 +371,10 @@ footer nav { grid-template-columns: 1fr auto; padding: 0 18px; } + .masthead nav { + gap: 12px; + font-size: 12px; + } .collection { display: none; } From 11ee9b3c4057b1a9069560eae1289fdd280cd92e Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:29:44 +0200 Subject: [PATCH 04/14] chore(release): prepare v2 production metadata --- README.md | 2 +- SECURITY.md | 2 ++ docs/compatibility.md | 2 ++ package-lock.json | 4 ++-- package.json | 4 ++-- scripts/verify-release.mjs | 11 +++++++++++ vercel.json | 7 +++++++ 7 files changed, 27 insertions(+), 5 deletions(-) create mode 100644 vercel.json diff --git a/README.md b/README.md index 0941e2a..25794e1 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ Initial wrapping creates one proxy and does not walk the graph. Nested proxies a ## Documentation -[Architecture](docs/architecture.md) · [API](docs/api.md) · [Supported types](docs/supported-types.md) · [Compatibility](docs/compatibility.md) · [Migration](docs/migration-v1-v2.md) · [Security](docs/security-and-trust.md) · [Contributing](CONTRIBUTING.md) +[Documentation site](https://readonly-view.nipesolutions.com) · [Architecture](docs/architecture.md) · [API](docs/api.md) · [Supported types](docs/supported-types.md) · [Compatibility](docs/compatibility.md) · [Migration](docs/migration-v1-v2.md) · [Security](docs/security-and-trust.md) · [Contributing](CONTRIBUTING.md) ## License diff --git a/SECURITY.md b/SECURITY.md index a695a27..9c0bc83 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,4 +2,6 @@ Security fixes are supported for the latest published major version. Report vulnerabilities through GitHub private vulnerability reporting for `NIPE-Solutions/readonly-view`; do not publish exploit details in an issue. +Public documentation is available at [readonly-view.nipesolutions.com](https://readonly-view.nipesolutions.com). + ReadonlyView is not a security sandbox. Unexpected source-reference escapes through supported paths, source mutation by the library, prototype pollution, or package-integrity failures are relevant reports. Existing source references, user function/getter side effects, and consumer-proxy behavior are outside the sandbox guarantee but may still reveal correctness defects. diff --git a/docs/compatibility.md b/docs/compatibility.md index 944d1ad..c9752aa 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -16,4 +16,6 @@ The emitted JavaScript targets ES2022. “Current browser” means the versions installed by the lockfile's Playwright release, not every historical browser with Proxy support. +Current documentation is published at [readonly-view.nipesolutions.com](https://readonly-view.nipesolutions.com). + On macOS 14, the current Playwright WebKit bundle has an upstream launch-protocol incompatibility. Local configuration omits that one project on that OS; the Linux CI matrix remains authoritative for WebKit support. diff --git a/package-lock.json b/package-lock.json index ea8f273..85db9e0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@nipe-solutions/readonly-view", - "version": "2.0.0-alpha.0", + "version": "2.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@nipe-solutions/readonly-view", - "version": "2.0.0-alpha.0", + "version": "2.0.0", "license": "MIT", "devDependencies": { "@eslint/js": "^10.0.1", diff --git a/package.json b/package.json index 3268feb..90e0a82 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@nipe-solutions/readonly-view", - "version": "2.0.0-alpha.0", + "version": "2.0.0", "packageManager": "npm@11.19.0", "description": "A deeply readonly, lazy, live view over mutable JavaScript data.", "type": "module", @@ -57,7 +57,7 @@ ], "author": "Nicholas Petrasek", "license": "MIT", - "homepage": "https://github.com/NIPE-Solutions/readonly-view#readme", + "homepage": "https://readonly-view.nipesolutions.com", "repository": { "type": "git", "url": "git+https://github.com/NIPE-Solutions/readonly-view.git" diff --git a/scripts/verify-release.mjs b/scripts/verify-release.mjs index 8d3e19d..5c2afaa 100644 --- a/scripts/verify-release.mjs +++ b/scripts/verify-release.mjs @@ -12,6 +12,10 @@ function assert(condition, message) { } assert(pkg.name === '@nipe-solutions/readonly-view', 'Unexpected package name'); +assert( + pkg.homepage === 'https://readonly-view.nipesolutions.com', + 'Homepage is stale', +); assert(pkg.version === lock.version, 'package-lock root version is stale'); assert( pkg.version === lock.packages[''].version, @@ -28,6 +32,13 @@ assert( 'Repository metadata is stale', ); +const vercel = JSON.parse(await readFile(resolve(root, 'vercel.json'), 'utf8')); +assert( + vercel.buildCommand === 'npm run build:website', + 'Unexpected Vercel build', +); +assert(vercel.outputDirectory === 'website/dist', 'Unexpected Vercel output'); + for (const file of [ 'LICENSE', 'README.md', diff --git a/vercel.json b/vercel.json new file mode 100644 index 0000000..ea81e93 --- /dev/null +++ b/vercel.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://openapi.vercel.sh/vercel.json", + "buildCommand": "npm run build:website", + "framework": null, + "installCommand": "npm ci", + "outputDirectory": "website/dist" +} From 9e6a3f4182c52450a3b3edb72d3f2eaaed131865 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:33:16 +0200 Subject: [PATCH 05/14] fix(release): enforce stable Vercel metadata --- SECURITY.md | 2 +- docs/compatibility.md | 2 +- scripts/verify-release.mjs | 3 +++ 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 9c0bc83..77c700b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,6 +2,6 @@ Security fixes are supported for the latest published major version. Report vulnerabilities through GitHub private vulnerability reporting for `NIPE-Solutions/readonly-view`; do not publish exploit details in an issue. -Public documentation is available at [readonly-view.nipesolutions.com](https://readonly-view.nipesolutions.com). +Canonical documentation URL: [readonly-view.nipesolutions.com](https://readonly-view.nipesolutions.com). ReadonlyView is not a security sandbox. Unexpected source-reference escapes through supported paths, source mutation by the library, prototype pollution, or package-integrity failures are relevant reports. Existing source references, user function/getter side effects, and consumer-proxy behavior are outside the sandbox guarantee but may still reveal correctness defects. diff --git a/docs/compatibility.md b/docs/compatibility.md index c9752aa..b437f8b 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -16,6 +16,6 @@ The emitted JavaScript targets ES2022. “Current browser” means the versions installed by the lockfile's Playwright release, not every historical browser with Proxy support. -Current documentation is published at [readonly-view.nipesolutions.com](https://readonly-view.nipesolutions.com). +Canonical documentation URL: [readonly-view.nipesolutions.com](https://readonly-view.nipesolutions.com). On macOS 14, the current Playwright WebKit bundle has an upstream launch-protocol incompatibility. Local configuration omits that one project on that OS; the Linux CI matrix remains authoritative for WebKit support. diff --git a/scripts/verify-release.mjs b/scripts/verify-release.mjs index 5c2afaa..be941f1 100644 --- a/scripts/verify-release.mjs +++ b/scripts/verify-release.mjs @@ -16,6 +16,7 @@ assert( pkg.homepage === 'https://readonly-view.nipesolutions.com', 'Homepage is stale', ); +assert(pkg.version === '2.0.0', 'Unexpected package version'); assert(pkg.version === lock.version, 'package-lock root version is stale'); assert( pkg.version === lock.packages[''].version, @@ -37,6 +38,8 @@ assert( vercel.buildCommand === 'npm run build:website', 'Unexpected Vercel build', ); +assert(vercel.framework === null, 'Unexpected Vercel framework'); +assert(vercel.installCommand === 'npm ci', 'Unexpected Vercel install'); assert(vercel.outputDirectory === 'website/dist', 'Unexpected Vercel output'); for (const file of [ From 6b60cfb24c1ca20900b6052cf2a26561ed66f602 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:37:35 +0200 Subject: [PATCH 06/14] ci: align deployment and stable release gates --- .github/workflows/ci.yml | 21 +++-- .github/workflows/release.yml | 28 ++++--- CONTRIBUTING.md | 23 +++++- docs/RELEASING.md | 82 +++++++++++++++---- .../2026-09-03-legal-deployment-release.md | 54 +++++++++--- 5 files changed, 167 insertions(+), 41 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1778991..6e62e90 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,14 +17,13 @@ jobs: quality: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 24 cache: npm - run: npm ci - - run: npm run check - - run: npm run package:artifact + - run: npm run release:check - name: Upload packed artifact uses: actions/upload-artifact@v7 with: @@ -34,9 +33,10 @@ jobs: include-hidden-files: true node-22: + needs: quality runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 22 @@ -47,13 +47,14 @@ jobs: - run: npm run test:package browser: + needs: quality runs-on: ubuntu-latest strategy: fail-fast: false matrix: browser: [chromium, firefox, webkit] steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 24 @@ -62,3 +63,13 @@ jobs: - run: npx playwright install --with-deps ${{ matrix.browser }} - run: npm run build - run: npm run test:browser -- --project=${{ matrix.browser }} + - name: Upload Playwright failure diagnostics + if: failure() + uses: actions/upload-artifact@v7 + with: + name: playwright-${{ matrix.browser }}-failure + path: | + playwright-report/ + test-results/ + if-no-files-found: warn + retention-days: 7 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8d00c75..2808595 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,7 +12,7 @@ on: type: choice options: [next, latest] confirmation: - description: Type publish VERSION with CHANNEL + description: Type publish 2.0.0 with latest required: true permissions: @@ -22,20 +22,23 @@ jobs: authorize: runs-on: ubuntu-latest steps: - - name: Require main and exact confirmation + - name: Require main and exact stable release confirmation env: ACTUAL_REF: ${{ github.ref }} + ACTUAL_VERSION: ${{ inputs.version }} + ACTUAL_CHANNEL: ${{ inputs.channel }} ACTUAL_CONFIRMATION: ${{ inputs.confirmation }} - EXPECTED_CONFIRMATION: publish ${{ inputs.version }} with ${{ inputs.channel }} run: | test "$ACTUAL_REF" = "refs/heads/main" - test "$ACTUAL_CONFIRMATION" = "$EXPECTED_CONFIRMATION" + test "$ACTUAL_VERSION" = "2.0.0" + test "$ACTUAL_CHANNEL" = "latest" + test "$ACTUAL_CONFIRMATION" = "publish 2.0.0 with latest" verify: needs: authorize runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 24 @@ -50,7 +53,8 @@ jobs: env: REQUESTED_CHANNEL: ${{ inputs.channel }} run: node scripts/verify-release-channel.mjs "$REQUESTED_CHANNEL" - - run: node scripts/verify-registry.mjs unpublished + - name: Verify 2.0.0 is absent from npm + run: node scripts/verify-registry.mjs unpublished browser: needs: verify @@ -60,7 +64,7 @@ jobs: matrix: browser: [chromium, firefox, webkit] steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 24 @@ -78,7 +82,7 @@ jobs: contents: read id-token: write steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 24 @@ -89,8 +93,12 @@ jobs: REQUESTED_VERSION: ${{ inputs.version }} run: test "$(node -p "require('./package.json').version")" = "$REQUESTED_VERSION" - run: npm run release:check + - name: Reconfirm 2.0.0 is absent from npm + run: node scripts/verify-registry.mjs unpublished - name: Publish through npm trusted publishing - run: npm publish --access public --tag ${{ inputs.channel }} + env: + REQUESTED_CHANNEL: ${{ inputs.channel }} + run: npm publish --access public --tag "$REQUESTED_CHANNEL" - name: Verify registry propagation run: node scripts/verify-registry.mjs published @@ -100,7 +108,7 @@ jobs: permissions: contents: write steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v7 - name: Create GitHub release env: GH_TOKEN: ${{ github.token }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f596305..e40a1ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Use Node.js 24 (`.nvmrc`) and npm. ```bash npm ci -npm run check +npm run release:check ``` ## Commands @@ -18,3 +18,24 @@ npm run check - `npm run build:website`: production documentation site. Add a failing regression test before fixing a defect. Tests should name an observable break and exercise real behavior. Keep changes focused, document public behavior, and explain API, compatibility, size, or security impact in the pull request. + +## Deployment and release changes + +Vercel's Git integration creates previews for pull requests and deploys +documentation from `main` to the custom domain +`https://readonly-view.nipesolutions.com`. Changes to `vercel.json`, public URLs, +legal routes, DNS expectations, or release automation must describe their preview +and production verification in the pull request. + +Publishing is restricted to the protected GitHub environment `npm` and the npm +trusted-publisher tuple `NIPE-Solutions/readonly-view`, `release.yml`, `npm`. +The stable release is dispatched from `main` with exactly `version=2.0.0`, +`channel=latest`, and `confirmation=publish 2.0.0 with latest`. After publication, +verify the npm metadata and import, provenance, the `v2.0.0` GitHub release, and +the production site; see [the release runbook](docs/RELEASING.md) for the exact +commands. + +Never attempt to overwrite or republish an npm version. A package defect requires +a reviewed patch release (and a precise deprecation warning when appropriate); a +site defect should be rolled back in Vercel and corrected on `main`. Do not +deprecate or otherwise mutate the old `immuview` package. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index cda841d..dfefd4b 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -1,16 +1,70 @@ # Releasing -Releases are manual and protected. - -1. Use Node 24 and run `npm ci`. -2. Update version and promote Unreleased notes. -3. Run `npm run release:check` and the browser matrix. -4. Review `npm pack --dry-run`, declarations, budgets, and license. -5. Configure npm trusted publishing for the `NIPE-Solutions/readonly-view` - repository and the `release.yml` workflow, with the `npm` GitHub environment - protected by required reviewers. -6. Dispatch Release from `main` with the exact version, the `next` or `latest` - channel, and the literal `publish VERSION with CHANNEL` confirmation. -7. Verify registry propagation and create the matching GitHub release. - -Stable versions use `latest`; prereleases use `next`. Never publish during implementation. +Releases are manual, protected, and run only from `main`. The current workflow is +locked to the first stable release: `@nipe-solutions/readonly-view@2.0.0` on the +`latest` npm channel. Its inputs remain versioned so a future release can update +the explicit authorization gate without redesigning the workflow. + +## Hosted documentation + +Vercel's Git integration owns documentation deployments for the +`NIPE-Solutions/readonly-view` repository. Pull requests receive preview +deployments; a merge to the production branch, `main`, creates the production +deployment using the committed `vercel.json`. The production project must have +`readonly-view.nipesolutions.com` attached as its custom domain with valid DNS +and TLS before npm publication. Verify the home page, all four legal routes, +`/robots.txt`, and `/sitemap.xml` on that HTTPS origin. + +If a documentation deployment is defective, restore the previous known-good +Vercel deployment immediately and follow with a reviewed revert or fix on +`main`. Do not publish a package merely to repair the hosted documentation. + +## One-time npm and GitHub setup + +Create a protected GitHub environment named `npm`, restrict deployments to +`main`, and require a reviewer when the repository plan supports it. Configure +the npm trusted publisher with this exact tuple: + +- repository owner/name: `NIPE-Solutions/readonly-view` +- workflow filename: `release.yml` +- GitHub environment: `npm` + +Use OIDC trusted publishing; do not add a long-lived npm token. + +## Stable 2.0.0 procedure + +1. On the reviewed `main` commit, use Node 24 and run `npm ci`, + `npm run release:check`, and `npm run test:browser`. +2. Review `npm pack --dry-run`, declarations, bundle budgets, license, and the + exact tarball. Confirm the production documentation checks above pass. +3. Confirm `npm view @nipe-solutions/readonly-view@2.0.0 version` returns an npm + `E404`; an existing version must never be overwritten. +4. Dispatch the protected workflow with exactly these inputs: + + ```bash + gh workflow run release.yml --ref main \ + -f version=2.0.0 \ + -f channel=latest \ + -f 'confirmation=publish 2.0.0 with latest' + ``` + +5. Approve the `npm` environment deployment, then monitor the publish job. It + reconfirms registry absence, publishes with provenance, waits for registry + propagation, and only then allows creation of GitHub release `v2.0.0`. +6. Verify the public result: + + ```bash + npm view @nipe-solutions/readonly-view@2.0.0 name version dist-tags.latest repository homepage + npm exec --yes --package=@nipe-solutions/readonly-view@2.0.0 -- \ + node -e "import('@nipe-solutions/readonly-view').then(m => console.log(typeof m.readonlyView))" + gh release view v2.0.0 --repo NIPE-Solutions/readonly-view + ``` + +The metadata must report version `2.0.0`, `latest` must resolve to `2.0.0`, the +homepage must be `https://readonly-view.nipesolutions.com`, the import must print +`function`, npm must show provenance, and the GitHub release must exist. + +npm versions are immutable: never attempt to republish `2.0.0`. If the package +is defective, deprecate it with a precise warning when appropriate, publish a +reviewed patch version, and move `latest` only through the guarded workflow. Do +not deprecate or otherwise mutate the old `immuview` package. diff --git a/docs/superpowers/plans/2026-09-03-legal-deployment-release.md b/docs/superpowers/plans/2026-09-03-legal-deployment-release.md index 837316f..773eabb 100644 --- a/docs/superpowers/plans/2026-09-03-legal-deployment-release.md +++ b/docs/superpowers/plans/2026-09-03-legal-deployment-release.md @@ -24,6 +24,7 @@ ### Task 1: Bilingual legal routes and production website metadata **Files:** + - Create: `website/privacy/index.html` - Create: `website/impressum/index.html` - Create: `website/de/datenschutz/index.html` @@ -43,6 +44,7 @@ - Modify: `test/integration/docs-examples.test.ts` **Interfaces:** + - Consumes: existing `.masthead`, `.brand`, footer, color tokens, and `npm run build:website`. - Produces: four stable legal routes, language cross-links, canonical production URLs, and multi-page Vite output under `website/dist`. - Produces: a crisp ReadonlyView tab-icon family derived from the existing `R` brand mark. @@ -53,10 +55,22 @@ Extend `scripts/verify-website.mjs` to read all five built HTML files and assert ```js const pages = new Map([ - ['privacy/index.html', ['Privacy Policy', 'Vercel Inc.', 'no non-essential cookies']], - ['impressum/index.html', ['Impressum', 'NIPE Solutions e.U.', 'ATU78464412']], - ['de/datenschutz/index.html', ['Datenschutzerklärung', 'Vercel Inc.', 'Datenschutzbehörde']], - ['de/impressum/index.html', ['Impressum', 'NIPE Solutions e.U.', 'FN 585066t']], + [ + 'privacy/index.html', + ['Privacy Policy', 'Vercel Inc.', 'no non-essential cookies'], + ], + [ + 'impressum/index.html', + ['Impressum', 'NIPE Solutions e.U.', 'ATU78464412'], + ], + [ + 'de/datenschutz/index.html', + ['Datenschutzerklärung', 'Vercel Inc.', 'Datenschutzbehörde'], + ], + [ + 'de/impressum/index.html', + ['Impressum', 'NIPE Solutions e.U.', 'FN 585066t'], + ], ]); ``` @@ -112,9 +126,7 @@ const source = { const view = readonlyView(source); expect(view.items[0]).toBe(view.map.get('selected')); expect([...view.set][0]).toBe(view.items[0]); -expect(() => Reflect.set(view.items[0], 'id', 2)).toThrow( - DirectMutationError, -); +expect(() => Reflect.set(view.items[0], 'id', 2)).toThrow(DirectMutationError); ``` - [ ] **Step 6: Add browser route coverage** @@ -124,8 +136,12 @@ Add a Playwright test that opens each route and checks its heading, language lin ```ts for (const [route, heading] of legalRoutes) { await page.goto(route); - await expect(page.getByRole('heading', { level: 1, name: heading })).toBeVisible(); - expect(await page.evaluate(() => document.body.scrollWidth)).toBeLessThanOrEqual( + await expect( + page.getByRole('heading', { level: 1, name: heading }), + ).toBeVisible(); + expect( + await page.evaluate(() => document.body.scrollWidth), + ).toBeLessThanOrEqual( await page.evaluate(() => document.documentElement.clientWidth), ); } @@ -142,6 +158,7 @@ Commit: `feat(website): add bilingual legal pages` ### Task 2: Vercel configuration and public metadata **Files:** + - Create: `vercel.json` - Modify: `package.json` - Modify: `package-lock.json` @@ -151,6 +168,7 @@ Commit: `feat(website): add bilingual legal pages` - Modify: `scripts/verify-release.mjs` **Interfaces:** + - Consumes: `npm run build:website` and `website/dist` from Task 1. - Produces: repeatable Vercel builds and a single canonical documentation origin across metadata. @@ -159,9 +177,15 @@ Commit: `feat(website): add bilingual legal pages` Extend `scripts/verify-release.mjs` with exact assertions: ```js -assert(pkg.homepage === 'https://readonly-view.nipesolutions.com', 'Homepage is stale'); +assert( + pkg.homepage === 'https://readonly-view.nipesolutions.com', + 'Homepage is stale', +); const vercel = JSON.parse(await readFile(resolve(root, 'vercel.json'), 'utf8')); -assert(vercel.buildCommand === 'npm run build:website', 'Unexpected Vercel build'); +assert( + vercel.buildCommand === 'npm run build:website', + 'Unexpected Vercel build', +); assert(vercel.outputDirectory === 'website/dist', 'Unexpected Vercel output'); ``` @@ -200,12 +224,14 @@ Commit: `chore(release): prepare v2 production metadata` ### Task 3: Reference-grade CI and guarded release workflow **Files:** + - Modify: `.github/workflows/ci.yml` - Modify: `.github/workflows/release.yml` - Modify: `docs/RELEASING.md` - Modify: `CONTRIBUTING.md` **Interfaces:** + - Consumes: `npm run release:check`, Playwright projects, packed artifact output, npm channel verifier. - Produces: dependency-ordered CI, failure diagnostics, and a stable-only guarded release path using GitHub environment `npm`. @@ -238,10 +264,12 @@ Commit: `ci: align deployment and stable release gates` ### Task 4: Finalize changelog and verify the release candidate **Files:** + - Modify: `CHANGELOG.md` - Modify: `docs/release-readiness.md` **Interfaces:** + - Consumes: completed Tasks 1–3 and version `2.0.0`. - Produces: an auditable stable changelog and exact local release evidence. @@ -276,11 +304,13 @@ Commit: `docs: finalize readonly-view 2.0.0 release notes` ### Task 5: Review, merge, and Vercel production deployment **Files:** + - External: GitHub pull request and CI - External: Vercel project for `NIPE-Solutions/readonly-view` - External: GoDaddy DNS for `nipesolutions.com` **Interfaces:** + - Consumes: reviewed release branch and `vercel.json`. - Produces: green `main`, Vercel preview/production deployments, DNS verification, and valid HTTPS at the production origin. @@ -311,12 +341,14 @@ Check status 200, canonical URL, title, home interaction, all four legal routes, ### Task 6: npm trusted publishing and irreversible stable release **Files:** + - External: GitHub environment `npm` - External: npm organization/package trusted-publisher settings - External: GitHub Actions Release run - External: npm package and GitHub release **Interfaces:** + - Consumes: green merge commit on `main`, exact version `2.0.0`, npm organization access, production documentation. - Produces: public `@nipe-solutions/readonly-view@2.0.0`, `latest` dist-tag, provenance, and GitHub `v2.0.0` release. From 1aabac7056c7313eb5714f73dbd834ba6b98ad88 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:46:36 +0200 Subject: [PATCH 07/14] fix(release): publish verified bootstrap artifact --- .github/workflows/release.yml | 36 +++++- CONTRIBUTING.md | 19 ++-- docs/RELEASING.md | 63 ++++++++--- docs/release-readiness.md | 21 +++- .../2026-09-03-legal-deployment-release.md | 30 +++-- package.json | 2 +- scripts/verify-registry.mjs | 19 +++- test/package/verify-registry.test.mjs | 105 ++++++++++++++++++ 8 files changed, 253 insertions(+), 42 deletions(-) create mode 100644 test/package/verify-registry.test.mjs diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2808595..1617efa 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -55,6 +55,18 @@ jobs: run: node scripts/verify-release-channel.mjs "$REQUESTED_CHANNEL" - name: Verify 2.0.0 is absent from npm run: node scripts/verify-registry.mjs unpublished + - name: Assert exactly one verified tarball + run: | + shopt -s nullglob + tarballs=(.artifacts/*.tgz) + test "${#tarballs[@]}" -eq 1 + - name: Upload verified release artifact + uses: actions/upload-artifact@v7 + with: + name: release-package-${{ github.sha }} + path: .artifacts/*.tgz + if-no-files-found: error + include-hidden-files: true browser: needs: verify @@ -87,18 +99,33 @@ jobs: with: node-version: 24 registry-url: https://registry.npmjs.org - - run: npm ci + - name: Download verified release artifact + uses: actions/download-artifact@v8 + with: + name: release-package-${{ github.sha }} + path: .artifacts - name: Verify requested version env: REQUESTED_VERSION: ${{ inputs.version }} run: test "$(node -p "require('./package.json').version")" = "$REQUESTED_VERSION" - - run: npm run release:check + - name: Select the single verified tarball + run: | + shopt -s nullglob + tarballs=(.artifacts/*.tgz) + test "${#tarballs[@]}" -eq 1 + printf 'VERIFIED_TARBALL=%s\n' "${tarballs[0]}" >> "$GITHUB_ENV" - name: Reconfirm 2.0.0 is absent from npm run: node scripts/verify-registry.mjs unpublished - - name: Publish through npm trusted publishing + - name: Publish verified tarball for initial package bootstrap env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} REQUESTED_CHANNEL: ${{ inputs.channel }} - run: npm publish --access public --tag "$REQUESTED_CHANNEL" + run: | + test -n "$NODE_AUTH_TOKEN" + npm publish "$VERIFIED_TARBALL" \ + --access public \ + --tag "$REQUESTED_CHANNEL" \ + --provenance - name: Verify registry propagation run: node scripts/verify-registry.mjs published @@ -117,5 +144,6 @@ jobs: run: >- gh release create "v$RELEASE_VERSION" --title "ReadonlyView v$RELEASE_VERSION" + --target "$GITHUB_SHA" --generate-notes ${{ inputs.channel == 'next' && '--prerelease' || '' }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e40a1ee..3f7a2a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,13 +27,18 @@ documentation from `main` to the custom domain legal routes, DNS expectations, or release automation must describe their preview and production verification in the pull request. -Publishing is restricted to the protected GitHub environment `npm` and the npm -trusted-publisher tuple `NIPE-Solutions/readonly-view`, `release.yml`, `npm`. -The stable release is dispatched from `main` with exactly `version=2.0.0`, -`channel=latest`, and `confirmation=publish 2.0.0 with latest`. After publication, -verify the npm metadata and import, provenance, the `v2.0.0` GitHub release, and -the production site; see [the release runbook](docs/RELEASING.md) for the exact -commands. +Publishing is restricted to the protected GitHub environment `npm`. The first +publication uses a short-lived granular `NPM_TOKEN` environment secret because +npm requires the package to exist before trusted-publisher setup; only the +publish job receives it, and it publishes the verified tarball with provenance. +Afterward, revoke the token, delete the secret, and configure the trusted- +publisher tuple `NIPE-Solutions/readonly-view`, `release.yml`, `npm` for future +releases. The stable release is dispatched from `main` with exactly +`version=2.0.0`, `channel=latest`, and +`confirmation=publish 2.0.0 with latest`. After publication, verify the npm +metadata and a fresh external consumer install, provenance, the SHA-targeted +`v2.0.0` GitHub release, and every production route; see +[the release runbook](docs/RELEASING.md) for the exact commands. Never attempt to overwrite or republish an npm version. A package defect requires a reviewed patch release (and a precise deprecation warning when appropriate); a diff --git a/docs/RELEASING.md b/docs/RELEASING.md index dfefd4b..d3a7f97 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -19,17 +19,35 @@ If a documentation deployment is defective, restore the previous known-good Vercel deployment immediately and follow with a reviewed revert or fix on `main`. Do not publish a package merely to repair the hosted documentation. -## One-time npm and GitHub setup +## First-publication authentication Create a protected GitHub environment named `npm`, restrict deployments to -`main`, and require a reviewer when the repository plan supports it. Configure -the npm trusted publisher with this exact tuple: +`main`, and require a reviewer when the repository plan supports it. Because npm +does not allow trusted-publisher setup until the package exists, the initial +`2.0.0` publication uses a short-lived granular npm access token: -- repository owner/name: `NIPE-Solutions/readonly-view` -- workflow filename: `release.yml` -- GitHub environment: `npm` +1. Immediately before dispatch, create a granular token with the shortest + practical expiry and only the package-write access needed for the + `@nipe-solutions` scope. Enable CI-compatible publication when npm's account + policy requires it. +2. Add it as an environment secret named `NPM_TOKEN` on the protected `npm` + environment, not as a repository-wide secret. Only the `publish` job reads + it. +3. After `2.0.0` exists and all checks below pass, configure the npm trusted + publisher with this exact tuple: -Use OIDC trusted publishing; do not add a long-lived npm token. + - repository owner/name: `NIPE-Solutions/readonly-view` + - workflow filename: `release.yml` + - GitHub environment: `npm` + +4. Delete the `NPM_TOKEN` GitHub environment secret and revoke the granular + token. For future versions, update the explicit release authorization and + remove `NODE_AUTH_TOKEN` from the publish step so npm authenticates through + the trusted publisher. + +The initial workflow uses the token for registry authentication and the +publish job's OIDC permission for `--provenance`; it is not an OIDC-only +publication. Never use a long-lived npm token. ## Stable 2.0.0 procedure @@ -49,20 +67,39 @@ Use OIDC trusted publishing; do not add a long-lived npm token. ``` 5. Approve the `npm` environment deployment, then monitor the publish job. It - reconfirms registry absence, publishes with provenance, waits for registry - propagation, and only then allows creation of GitHub release `v2.0.0`. + downloads the single tarball produced by the verified job, reconfirms + registry absence, publishes those exact bytes with provenance, waits for + registry propagation, and only then creates GitHub release `v2.0.0` at the + immutable workflow commit. 6. Verify the public result: ```bash npm view @nipe-solutions/readonly-view@2.0.0 name version dist-tags.latest repository homepage - npm exec --yes --package=@nipe-solutions/readonly-view@2.0.0 -- \ - node -e "import('@nipe-solutions/readonly-view').then(m => console.log(typeof m.readonlyView))" - gh release view v2.0.0 --repo NIPE-Solutions/readonly-view + test -n "$(npm view @nipe-solutions/readonly-view@2.0.0 dist.attestations.url)" + + consumer_dir="$(mktemp -d)" + ( + cd "$consumer_dir" + npm init --yes >/dev/null + npm install --ignore-scripts --save-exact @nipe-solutions/readonly-view@2.0.0 + node --input-type=module -e \ + "import('@nipe-solutions/readonly-view').then(m => console.log(typeof m.readonlyView))" + ) + + for route in / /privacy/ /impressum/ /de/datenschutz/ /de/impressum/ /robots.txt /sitemap.xml; do + curl --fail --silent --show-error --location \ + "https://readonly-view.nipesolutions.com${route}" >/dev/null + done + + gh release view v2.0.0 --repo NIPE-Solutions/readonly-view \ + --json tagName,targetCommitish,url ``` The metadata must report version `2.0.0`, `latest` must resolve to `2.0.0`, the homepage must be `https://readonly-view.nipesolutions.com`, the import must print -`function`, npm must show provenance, and the GitHub release must exist. +`function` from the temporary consumer, the attestation URL must be nonempty, +all production requests must succeed over HTTPS, and the GitHub release target +must match the dispatched `main` SHA. Remove `consumer_dir` after inspection. npm versions are immutable: never attempt to republish `2.0.0`. If the package is defective, deprecate it with a precise warning when appropriate, publish a diff --git a/docs/release-readiness.md b/docs/release-readiness.md index 4fe960d..21fe5a8 100644 --- a/docs/release-readiness.md +++ b/docs/release-readiness.md @@ -1,6 +1,8 @@ # ReadonlyView 2.0 release readiness -Status: alpha implementation complete; main-branch CI and npm trusted-publisher configuration remain external release prerequisites. No package or website was published by this work. +Status: alpha implementation complete; main-branch CI, the protected `npm` +environment, and first-publication authentication remain external release +prerequisites. No package or website was published by this work. ## 1. Architecture @@ -36,7 +38,15 @@ Vite emits ES2022 ESM and CommonJS builds; TypeScript plus Rollup emits one decl ## 9. CI and release -CI runs the Node 24 quality gate, Node 22 compatibility, and Chromium/Firefox/WebKit jobs. Release is manual, main-only, exact-confirmation gated, environment protected, checks version/channel policy and registry availability, repeats quality and browsers, uses npm OIDC trusted publishing, waits for propagation, then creates a GitHub release. Repository-side npm trusted-publisher and environment-reviewer settings must be configured before use. +CI runs the Node 24 quality gate, Node 22 compatibility, and +Chromium/Firefox/WebKit jobs. Release is manual, main-only, exact-confirmation +gated, environment protected, checks version/channel policy and registry +availability, carries the verified tarball through the browser gate, and waits +for propagation before creating a SHA-targeted GitHub release. The first +publication uses a short-lived granular `NPM_TOKEN` environment secret plus +OIDC provenance. After the package exists, that token must be revoked and +deleted and the documented npm trusted publisher must replace it for future +releases. ## 10. Documentation @@ -56,7 +66,12 @@ ReadonlyView is not a sandbox. Generic/overloaded callable types cannot always b ## 14. Recommended follow-up -Run the branch on GitHub Actions, configure the npm trusted publisher and protected `npm` environment, decide the final alpha/stable version, promote `Unreleased` changelog notes, and only then invoke the manual release workflow. Bun, Deno, older TypeScript, and additional native adapters should be claimed only after dedicated CI. +Run the branch on GitHub Actions, configure the protected `npm` environment and +its short-lived first-publication token, decide the final alpha/stable version, +promote `Unreleased` changelog notes, and only then invoke the manual release +workflow. Configure npm trusted publishing and remove the bootstrap token after +the initial package exists. Bun, Deno, older TypeScript, and additional native +adapters should be claimed only after dedicated CI. ## Local verification diff --git a/docs/superpowers/plans/2026-09-03-legal-deployment-release.md b/docs/superpowers/plans/2026-09-03-legal-deployment-release.md index 773eabb..de06b74 100644 --- a/docs/superpowers/plans/2026-09-03-legal-deployment-release.md +++ b/docs/superpowers/plans/2026-09-03-legal-deployment-release.md @@ -4,7 +4,7 @@ **Goal:** Add bilingual legal pages, production Vercel deployment, reference-grade GitHub automation, and publish `@nipe-solutions/readonly-view@2.0.0` as a verified stable release. -**Architecture:** Keep the Vite site framework-free and add four static legal entry points sharing the existing design system. Use Vercel Git integration for preview/production deployments and the guarded GitHub release workflow for npm OIDC publication after all local and hosted checks pass. +**Architecture:** Keep the Vite site framework-free and add four static legal entry points sharing the existing design system. Use Vercel Git integration for preview/production deployments and the guarded GitHub release workflow for initial token-authenticated publication with OIDC provenance after all local and hosted checks pass; switch future releases to npm trusted publishing after the package exists. **Tech Stack:** HTML, CSS, TypeScript, Vite 8, Playwright, GitHub Actions, Vercel, GoDaddy DNS, npm trusted publishing. @@ -247,7 +247,7 @@ Use `actions/checkout@v7`, retain `actions/setup-node@v7` and `actions/upload-ar - [ ] **Step 3: Tighten stable release validation** -Use `actions/checkout@v7`, keep exact confirmation `publish 2.0.0 with latest`, require `main`, use environment `npm`, grant `id-token: write` only to publish, verify `2.0.0` is absent before publish, then verify registry propagation before the GitHub release. Preserve generic version inputs for future releases but enforce stable/latest through `verify-release-channel.mjs`. +Use `actions/checkout@v7`, keep exact confirmation `publish 2.0.0 with latest`, require `main`, use environment `npm`, grant `id-token: write` only to publish, verify `2.0.0` is absent before publish, carry exactly one verified tarball into the publish job, and verify registry propagation before a SHA-targeted GitHub release. Use a short-lived granular `NPM_TOKEN` environment secret only for the initial package bootstrap, with `--provenance`; remove it after trusted publishing can be configured. Preserve generic version inputs for future releases but enforce stable/latest through `verify-release-channel.mjs`. - [ ] **Step 4: Document hosted deployment and publication** @@ -356,9 +356,9 @@ Check status 200, canonical URL, title, home interaction, all four legal routes, Create the repository environment `npm`, restrict it to `main`, and add the authenticated owner as a required reviewer when the repository plan supports reviewers. Do not add a long-lived npm token. -- [ ] **Step 2: Configure npm trusted publishing** +- [ ] **Step 2: Configure first-publication authentication** -In npm organization/package settings, configure repository `NIPE-Solutions/readonly-view`, workflow `release.yml`, environment `npm`. If npm cannot create the package through OIDC, perform only the minimum authenticated first-publication setup allowed by npm, then retain OIDC for future releases. +Create a short-lived granular npm token with only the required `@nipe-solutions` package-write access and store it as the `NPM_TOKEN` secret on the protected `npm` environment. The initial workflow uses that token only in the publish job and uses OIDC for `--provenance`; it is not OIDC-only. - [ ] **Step 3: Reconfirm registry absence and commit identity** @@ -385,13 +385,25 @@ Run: ```bash npm view @nipe-solutions/readonly-view@2.0.0 name version dist-tags.latest repository homepage -npm exec --yes --package=@nipe-solutions/readonly-view@2.0.0 -- \ - node -e "import('@nipe-solutions/readonly-view').then(m => console.log(typeof m.readonlyView))" -gh release view v2.0.0 --repo NIPE-Solutions/readonly-view +test -n "$(npm view @nipe-solutions/readonly-view@2.0.0 dist.attestations.url)" +consumer_dir="$(mktemp -d)" +( + cd "$consumer_dir" + npm init --yes >/dev/null + npm install --ignore-scripts --save-exact @nipe-solutions/readonly-view@2.0.0 + node --input-type=module -e \ + "import('@nipe-solutions/readonly-view').then(m => console.log(typeof m.readonlyView))" +) +gh release view v2.0.0 --repo NIPE-Solutions/readonly-view \ + --json tagName,targetCommitish,url ``` -Expected: exact name/version, `latest` equals `2.0.0`, production homepage, import prints `function`, provenance is visible in npm, and the GitHub release exists. +Expected: exact name/version, `latest` equals `2.0.0`, production homepage, the temporary consumer import prints `function`, provenance is visible in npm, and the GitHub release targets the dispatched SHA. -- [ ] **Step 6: Record final release evidence** +- [ ] **Step 6: Switch future releases to trusted publishing** + +In npm package settings, configure repository `NIPE-Solutions/readonly-view`, workflow `release.yml`, environment `npm`. Delete the `NPM_TOKEN` GitHub environment secret, revoke the granular token, and remove `NODE_AUTH_TOKEN` from the publish step when preparing the next release. + +- [ ] **Step 7: Record final release evidence** Update the release-readiness record or GitHub release notes with the production site, CI run, npm version, provenance, tarball integrity, and known limitations. Do not modify the old `immuview` package. diff --git a/package.json b/package.json index 90e0a82..5535d09 100644 --- a/package.json +++ b/package.json @@ -41,7 +41,7 @@ "test": "npm run test:unit", "test:unit": "vitest run --project unit --passWithNoTests", "test:types": "tsc --project test/types/tsconfig.json --noEmit", - "test:package": "npm run build:dist && node --test test/package/verify-package.test.mjs", + "test:package": "npm run build:dist && node --test test/package/verify-package.test.mjs test/package/verify-registry.test.mjs", "test:size": "npm run build:dist && node scripts/check-bundle-size.mjs", "test:website": "npm run build:website && node scripts/verify-website.mjs", "test:browser": "playwright test", diff --git a/scripts/verify-registry.mjs b/scripts/verify-registry.mjs index 510a48c..68e0c25 100644 --- a/scripts/verify-registry.mjs +++ b/scripts/verify-registry.mjs @@ -10,7 +10,15 @@ const pkg = JSON.parse( const specifier = `${pkg.name}@${pkg.version}`; const mode = process.argv[2]; -async function registryVersion() { +function npmErrorCode(error) { + try { + return JSON.parse(error.stdout)?.error?.code; + } catch { + return undefined; + } +} + +async function registryVersion({ allowNotFound = false } = {}) { try { const { stdout } = await exec('npm', [ 'view', @@ -19,19 +27,20 @@ async function registryVersion() { '--json', ]); return JSON.parse(stdout); - } catch { - return undefined; + } catch (error) { + if (allowNotFound && npmErrorCode(error) === 'E404') return undefined; + throw error; } } if (mode === 'unpublished') { - if ((await registryVersion()) !== undefined) { + if ((await registryVersion({ allowNotFound: true })) !== undefined) { throw new Error(`${specifier} already exists on npm`); } console.log(`${specifier} is available on npm`); } else if (mode === 'published') { for (let attempt = 1; attempt <= 12; attempt += 1) { - if ((await registryVersion()) === pkg.version) { + if ((await registryVersion({ allowNotFound: true })) === pkg.version) { console.log(`${specifier} is visible on npm`); process.exit(0); } diff --git a/test/package/verify-registry.test.mjs b/test/package/verify-registry.test.mjs new file mode 100644 index 0000000..1374bfa --- /dev/null +++ b/test/package/verify-registry.test.mjs @@ -0,0 +1,105 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { mkdtemp, rm } from 'node:fs/promises'; +import { createServer } from 'node:http'; +import { tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; +import { promisify } from 'node:util'; +import test from 'node:test'; + +const exec = promisify(execFile); +const root = resolve(import.meta.dirname, '..', '..'); +const verifier = resolve(root, 'scripts/verify-registry.mjs'); + +async function runVerifier(registry) { + const cache = await mkdtemp(join(tmpdir(), 'readonly-view-npm-cache-')); + try { + try { + const result = await exec( + process.execPath, + [verifier, 'unpublished'], + { + cwd: root, + env: { + ...process.env, + npm_config_cache: cache, + npm_config_fetch_retries: '0', + npm_config_fetch_timeout: '1000', + npm_config_registry: registry, + }, + }, + ); + return { ...result, exitCode: 0 }; + } catch (error) { + return { + stdout: error.stdout ?? '', + stderr: error.stderr ?? '', + exitCode: error.code, + }; + } + } finally { + await rm(cache, { force: true, recursive: true }); + } +} + +async function withRegistryResponse(statusCode, body, assertion) { + const server = createServer((_request, response) => { + response.writeHead(statusCode, { 'content-type': 'application/json' }); + response.end(JSON.stringify(body)); + }); + await new Promise((resolveListen) => + server.listen(0, '127.0.0.1', resolveListen), + ); + const { port } = server.address(); + try { + await assertion(`http://127.0.0.1:${port}/`); + } finally { + await new Promise((resolveClose, rejectClose) => + server.close((error) => + error ? rejectClose(error) : resolveClose(), + ), + ); + } +} + +test('unpublished mode accepts the registry package-not-found response', async () => { + await withRegistryResponse( + 404, + { error: 'Not found' }, + async (registry) => { + const result = await runVerifier(registry); + assert.equal(result.exitCode, 0); + assert.match(result.stdout, /is available on npm/); + }, + ); +}); + +for (const [statusCode, label] of [ + [401, 'authentication'], + [500, 'server'], +]) { + test(`unpublished mode rejects an npm ${label} error`, async () => { + await withRegistryResponse( + statusCode, + { error: `${label} failure` }, + async (registry) => { + const result = await runVerifier(registry); + assert.notEqual(result.exitCode, 0); + }, + ); + }); +} + +test('unpublished mode rejects a registry network error', async () => { + const server = createServer(); + await new Promise((resolveListen) => + server.listen(0, '127.0.0.1', resolveListen), + ); + const { port } = server.address(); + await new Promise((resolveClose, rejectClose) => + server.close((error) => (error ? rejectClose(error) : resolveClose())), + ); + + const result = await runVerifier(`http://127.0.0.1:${port}/`); + assert.notEqual(result.exitCode, 0); +}); From b7761aa7d2a2e57cc02c9c913f1a4095af5a88bf Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:50:10 +0200 Subject: [PATCH 08/14] docs: require 2fa bypass for bootstrap token --- docs/RELEASING.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/RELEASING.md b/docs/RELEASING.md index d3a7f97..c671763 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -27,9 +27,11 @@ does not allow trusted-publisher setup until the package exists, the initial `2.0.0` publication uses a short-lived granular npm access token: 1. Immediately before dispatch, create a granular token with the shortest - practical expiry and only the package-write access needed for the - `@nipe-solutions` scope. Enable CI-compatible publication when npm's account - policy requires it. + practical expiry. Scope its package and organization permissions only as + narrowly as npm permits for the initial `@nipe-solutions/readonly-view` + publication, grant the required package write access, and select the token's + `Bypass 2FA` option. Bypassing 2FA is required for this non-interactive direct + publication because GitHub Actions cannot enter a one-time password. 2. Add it as an environment secret named `NPM_TOKEN` on the protected `npm` environment, not as a repository-wide secret. Only the `publish` job reads it. @@ -40,10 +42,11 @@ does not allow trusted-publisher setup until the package exists, the initial - workflow filename: `release.yml` - GitHub environment: `npm` -4. Delete the `NPM_TOKEN` GitHub environment secret and revoke the granular - token. For future versions, update the explicit release authorization and - remove `NODE_AUTH_TOKEN` from the publish step so npm authenticates through - the trusted publisher. +4. Immediately after the trusted publisher is configured, delete the + `NPM_TOKEN` GitHub environment secret and revoke the granular token before + any further release work. For future versions, update the explicit release + authorization and remove `NODE_AUTH_TOKEN` from the publish step so npm + authenticates through the trusted publisher. The initial workflow uses the token for registry authentication and the publish job's OIDC permission for `--provenance`; it is not an OIDC-only From da7b99c46232a79414609626b5439478d660618c Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 22:55:22 +0200 Subject: [PATCH 09/14] docs: finalize readonly-view 2.0.0 release notes --- CHANGELOG.md | 6 +-- docs/release-readiness.md | 71 ++++++++++++++++++++++++++------- package.json | 3 +- scripts/verify-release.mjs | 4 +- test/package/verify-package.mjs | 1 + 5 files changed, 65 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 755ef82..a9add8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +## 2.0.0 - 2026-09-03 + ### Breaking Changes - Renamed `immuview` to `@nipe-solutions/readonly-view`. @@ -27,7 +29,3 @@ ### Documentation - Rewritten around readonly-view ownership. - -## 2.0.0 - -Prepared but not released. Promote Unreleased notes when publishing. diff --git a/docs/release-readiness.md b/docs/release-readiness.md index 21fe5a8..a317447 100644 --- a/docs/release-readiness.md +++ b/docs/release-readiness.md @@ -1,8 +1,10 @@ # ReadonlyView 2.0 release readiness -Status: alpha implementation complete; main-branch CI, the protected `npm` -environment, and first-publication authentication remain external release -prerequisites. No package or website was published by this work. +Status: the stable `2.0.0` release candidate passed its complete local gate on +2026-09-03 using macOS 14.6.1 arm64, Node 24.20.0, and npm 11.19.0. Main-branch +CI, Vercel production deployment, the protected `npm` environment, and +first-publication authentication remain external release prerequisites. No +package or website was published by this work. ## 1. Architecture @@ -30,11 +32,29 @@ Separate top-level calls create separate membranes; passing an existing view ret ## 7. Tests -The local suite currently contains 72 runtime tests across 21 files, plus strict compile-time tests. It covers mutation routes, descriptors, frozen/sealed/non-extensible values, liveness, identity, cycles, native adapters, randomized graphs, documentation examples, and regression cases from the final independent review. Coverage evidence: 91.34% statements, 89.11% branches, 93.10% functions, and 96.41% lines. +The release-candidate run passed 77 runtime tests across 21 files and the strict +compile-time suite. The package boundary run passed five more tests: one real +packed-consumer test and four unpublished-registry classification tests. It +covers mutation routes, descriptors, frozen/sealed/non-extensible values, +liveness, identity, cycles, native adapters, randomized graphs, documentation +examples, and regression cases from the final independent review. A fresh +coverage run passed the same 77 tests and measured 91.34% statements, 89.11% +branches, 93.10% functions, and 96.41% lines. ## 8. Package and build -Vite emits ES2022 ESM and CommonJS builds; TypeScript plus Rollup emits one declaration entry. The real six-file npm tarball is installed into an isolated consumer and exercised through ESM, CommonJS, strict TypeScript, esbuild, tree shaking, and blocked private imports. Runtime dependencies: zero. +Vite emits ES2022 ESM and CommonJS builds; TypeScript plus Rollup emits one +declaration entry. The exact seven-file npm tarball contains `CHANGELOG.md`, +`LICENSE`, `README.md`, `package.json`, `dist/index.js`, `dist/index.cjs`, and +`dist/index.d.ts`. It contains no tests, website source, benchmarks, source +maps, or private modules. The tarball is installed into an isolated consumer +and exercised through ESM, CommonJS, strict TypeScript, esbuild, tree shaking, +and blocked private imports. Runtime dependencies: zero. + +The inspected `.artifacts/nipe-solutions-readonly-view-2.0.0.tgz` is 6,971 B +packed and 33,691 B unpacked. Its SHA-1 is +`de84bb58a5ab30d6cfa3152f26d491e59d5aee82`; npm reported integrity +`sha512-vXQXfQNoO7LeTxFexZxSDY93NUClX04ZRl1CFjH8jCIcBIkwrUGL5uD5wkpMYvX05PMjIv+XefQ8I9LSbcbQmw==`. ## 9. CI and release @@ -48,30 +68,51 @@ OIDC provenance. After the package exists, that token must be revoked and deleted and the documented npm trusted publisher must replace it for future releases. +The local browser command passed all 22 scheduled tests: 11 on Chromium and 11 +on Firefox. Playwright deliberately excluded WebKit on this macOS 14 host under +the repository's documented upstream-compatibility rule; the Linux CI WebKit +job remains required. + ## 10. Documentation The repository contains a rewritten README, API, guarantees, compatibility, supported-types, architecture, security/trust, performance, migration, FAQ, contribution, release, security-policy, changelog, and five decision records. The framework-free documentation website mirrors these semantics and has interactive runtime examples and responsive browser tests. ## 11. Size -Current measured artifacts: minified ESM 5,807 B (7,000 B budget), minified+gzip ESM 1,900 B (2,500 B), declarations 2,026 B (2,500 B), packed tarball 6,521 B (10,000 B). +Release-candidate measurements: minified ESM 5,807 B (7,000 B budget), +minified+gzip ESM 1,900 B (2,500 B), declarations 2,026 B (2,500 B), packed +tarball 6,971 B (10,000 B), and unpacked tarball 33,691 B. ## 12. Benchmark summary -On Node 24.20.0, macOS arm64, 100,000 iterations measured: view creation 26.20 ms, first nested access 77.04 ms, repeated nested read 15.38 ms, deep read 23.52 ms, array iteration 1,484.39 ms, Map read 20.69 ms, Set iteration 40.86 ms, and Date read 15.41 ms. These are diagnostic local results, not marketing claims; see the methodology for caveats. +On Node 24.20.0, macOS arm64, 100,000 iterations measured: view creation 26.90 +ms, first nested access 77.62 ms, repeated nested read 15.34 ms, deep read 23.88 +ms, array iteration 1,446.00 ms, Map read 20.00 ms, Set iteration 40.35 ms, and +Date read 16.05 ms. The required 100-iteration benchmark smoke also passed as +part of `release:check`. These are diagnostic local results, not marketing +claims; see the methodology for caveats. ## 13. Known limitations -ReadonlyView is not a sandbox. Generic/overloaded callable types cannot always be transformed without losing signature information. Custom class views do not preserve `instanceof`; private fields can reject proxy receivers. Cross-realm and consumer-proxy behavior is limited by the supplied realm/proxy. WebKit could not launch under the local macOS 14 Playwright bundle and must be proven by the Linux CI job. +ReadonlyView is not a sandbox. Generic/overloaded callable types cannot always +be transformed without losing signature information. Custom class views do +not preserve `instanceof`; private fields can reject proxy receivers. +Cross-realm and consumer-proxy behavior is limited by the supplied realm/proxy. +WebKit is excluded locally on macOS 14 and must be proven by the Linux CI job. ## 14. Recommended follow-up -Run the branch on GitHub Actions, configure the protected `npm` environment and -its short-lived first-publication token, decide the final alpha/stable version, -promote `Unreleased` changelog notes, and only then invoke the manual release -workflow. Configure npm trusted publishing and remove the bootstrap token after -the initial package exists. Bun, Deno, older TypeScript, and additional native -adapters should be claimed only after dedicated CI. +Push the reviewed branch and open a pull request; require green Node 24 quality, +Node 22 compatibility, Chromium, Firefox, WebKit, and Vercel preview checks. +After merge, require green `main` CI, link the Vercel project, configure the +exact Vercel-provided GoDaddy DNS record, and verify HTTPS plus every production +route. Then configure the protected `npm` environment and short-lived granular +bootstrap token, dispatch the exact stable release, and verify registry +propagation, provenance, dist-tags, consumer import, and the SHA-targeted GitHub +release. Finally revoke and delete the bootstrap token and configure the +documented npm trusted publisher for future OIDC releases. Bun, Deno, older +TypeScript, and additional native adapters should be claimed only after +dedicated CI. ## Local verification @@ -81,4 +122,6 @@ npm run release:check npm run test:browser npm run coverage npm run benchmark +npm pack --dry-run --json +tar -tzf .artifacts/nipe-solutions-readonly-view-2.0.0.tgz ``` diff --git a/package.json b/package.json index 5535d09..d260243 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,8 @@ "./package.json": "./package.json" }, "files": [ - "dist" + "dist", + "CHANGELOG.md" ], "sideEffects": false, "engines": { diff --git a/scripts/verify-release.mjs b/scripts/verify-release.mjs index be941f1..e022172 100644 --- a/scripts/verify-release.mjs +++ b/scripts/verify-release.mjs @@ -24,7 +24,9 @@ assert( ); assert(pkg.license === 'MIT', 'Package license must be MIT'); assert( - pkg.files.length === 1 && pkg.files[0] === 'dist', + pkg.files.length === 2 && + pkg.files.includes('dist') && + pkg.files.includes('CHANGELOG.md'), 'files allowlist changed', ); assert(pkg.sideEffects === false, 'Package must remain side-effect free'); diff --git a/test/package/verify-package.mjs b/test/package/verify-package.mjs index 89ec76f..28c0ac2 100644 --- a/test/package/verify-package.mjs +++ b/test/package/verify-package.mjs @@ -20,6 +20,7 @@ export async function verifyPackage() { const [packed] = JSON.parse(stdout); const files = packed.files.map((entry) => entry.path).sort(); const expectedFiles = [ + 'CHANGELOG.md', 'LICENSE', 'README.md', 'dist/index.cjs', From 009e32db144bc56130546cd28b1dcd0c54faa3e7 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 23:05:20 +0200 Subject: [PATCH 10/14] test(website): isolate narrow masthead overflow --- test/browser/website.spec.ts | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/test/browser/website.spec.ts b/test/browser/website.spec.ts index 098cd73..3af8523 100644 --- a/test/browser/website.spec.ts +++ b/test/browser/website.spec.ts @@ -71,6 +71,17 @@ for (const [route, heading, language] of legalRoutes) { expect(stylesheets).toEqual( stylesheets.map(({ url }) => ({ status: 200, url })), ); + if (width === 320 && route.startsWith('/de/')) { + const mastheadWidths = await page + .locator('.masthead') + .evaluate((masthead) => ({ + client: masthead.clientWidth, + scroll: masthead.scrollWidth, + })); + expect(mastheadWidths.scroll).toBeLessThanOrEqual( + mastheadWidths.client, + ); + } expect( await page.evaluate(() => document.body.scrollWidth), ).toBeLessThanOrEqual( From d37b5e78505d11c4c1e521acf4a6a0e4d29cb4c2 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 23:08:51 +0200 Subject: [PATCH 11/14] fix(website): prevent mobile masthead overflow --- website/styles.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/styles.css b/website/styles.css index c6970bf..3ec167c 100644 --- a/website/styles.css +++ b/website/styles.css @@ -368,7 +368,7 @@ footer nav { } @media (max-width: 720px) { .masthead { - grid-template-columns: 1fr auto; + grid-template-columns: minmax(0, 1fr) auto; padding: 0 18px; } .masthead nav { From cda4e3d99e7f039753ef94e7237703b3bde50b11 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 23:11:37 +0200 Subject: [PATCH 12/14] test(website): report overflowing elements --- test/browser/website.spec.ts | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/test/browser/website.spec.ts b/test/browser/website.spec.ts index 3af8523..f46ed41 100644 --- a/test/browser/website.spec.ts +++ b/test/browser/website.spec.ts @@ -82,11 +82,37 @@ for (const [route, heading, language] of legalRoutes) { mastheadWidths.client, ); } + const layout = await page.evaluate(() => { + const viewport = document.documentElement.clientWidth; + const overflow = Array.from( + document.querySelectorAll('body *'), + ).flatMap((element) => { + const rect = element.getBoundingClientRect(); + if (rect.left >= 0 && Math.ceil(rect.right) <= viewport) { + return []; + } + return [ + { + element: + element.tagName.toLowerCase() + + (element.className + ? `.${element.className.split(' ').join('.')}` + : ''), + left: Number(rect.left.toFixed(2)), + right: Number(rect.right.toFixed(2)), + }, + ]; + }); + return { + body: document.body.scrollWidth, + overflow, + viewport, + }; + }); expect( - await page.evaluate(() => document.body.scrollWidth), - ).toBeLessThanOrEqual( - await page.evaluate(() => document.documentElement.clientWidth), - ); + layout.body, + JSON.stringify(layout.overflow), + ).toBeLessThanOrEqual(layout.viewport); }); } } From 3fcffff5e2e2f6a5635e96caacabea2ea8f930a3 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 23:14:14 +0200 Subject: [PATCH 13/14] test(website): diagnose internal layout overflow --- test/browser/website.spec.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/test/browser/website.spec.ts b/test/browser/website.spec.ts index f46ed41..da9b005 100644 --- a/test/browser/website.spec.ts +++ b/test/browser/website.spec.ts @@ -85,14 +85,19 @@ for (const [route, heading, language] of legalRoutes) { const layout = await page.evaluate(() => { const viewport = document.documentElement.clientWidth; const overflow = Array.from( - document.querySelectorAll('body *'), + document.querySelectorAll('body, body *'), ).flatMap((element) => { const rect = element.getBoundingClientRect(); - if (rect.left >= 0 && Math.ceil(rect.right) <= viewport) { + if ( + rect.left >= 0 && + Math.ceil(rect.right) <= viewport && + element.scrollWidth <= element.clientWidth + ) { return []; } return [ { + client: element.clientWidth, element: element.tagName.toLowerCase() + (element.className @@ -100,6 +105,7 @@ for (const [route, heading, language] of legalRoutes) { : ''), left: Number(rect.left.toFixed(2)), right: Number(rect.right.toFixed(2)), + scroll: element.scrollWidth, }, ]; }); From 8b807ed618eca066166de6b1196d0ac1d729d208 Mon Sep 17 00:00:00 2001 From: Nicholas Petrasek Date: Thu, 3 Sep 2026 23:17:18 +0200 Subject: [PATCH 14/14] fix(website): wrap narrow legal headings --- website/legal.css | 1 + 1 file changed, 1 insertion(+) diff --git a/website/legal.css b/website/legal.css index ec032da..553700f 100644 --- a/website/legal.css +++ b/website/legal.css @@ -45,6 +45,7 @@ margin: 0 0 18px; font-size: 27px; letter-spacing: -0.025em; + overflow-wrap: anywhere; } .legal-content p, .legal-content li {