fix(PRO-349): accept Next 16 as a peer dependency by alistairsmith-tech · Pull Request #54 · spurintel/javascript

alistairsmith-tech · 2026-08-10T14:41:04Z

@spur.us/monocle-nextjs would not install into a Next 16 project. Found while testing the PRO-323 AI install prompts against a real app.

Part of PRO-349.

The bug

The peer range stopped at ^15.2.3:

- "next": "^13.5.7 || ^14.2.25 || ^15.2.3"+ "next": "^13.5.7 || ^14.2.25 || ^15.2.3 || ^16.0.0"

Next 16.3.0 is current, so npm install @spur.us/monocle-nextjs failed peer resolution outright. No published version, including the 0.5.1 canary, listed Next 16. This blocked the manual onboarding path as much as the AI one, and pushed users toward --legacy-peer-deps or a project-wide .npmrc, both of which have effects well beyond this package.

The SDK already works on Next 16 once installed, so only the range was out of date.

Why this change cannot break anyone

Widening a peer range is purely additive. Consumers on Next 13, 14 and 15 resolve exactly as before, and no runtime code changed. The only behavioural difference is that an install which previously errored now succeeds.

Verified that the combination genuinely works rather than just permitting it:

tsc --noEmit clean against Next 16.3.0
next build succeeds, all 6 pages generated
Dev server boots, homepage 200, loader fires with the publishable key inlined into the client chunk
Range satisfies 15.2.3, 16.0.0, 16.3.0, and correctly rejects 17.0.0
pnpm build and pnpm lint pass across all 5 packages
vitest run passes in monocle-react (7 tests) and monocle-backend (9 tests)

What was deliberately dropped from this PR

An earlier revision also moved the React SDK's loader from mcl.spur.us to js.mcl.io, because the security docs tell customers to allowlist https://*.mcl.io and mcl.spur.us does not match that wildcard.

That has been reverted. Any existing customer running this SDK behind a CSP must have allowlisted mcl.spur.us for it to work at all, so changing the requested host breaks them on update unless they widen their policy first. Release notes cannot retroactively change a deployed CSP, so there is no way to make that rename risk-free for existing users.

The CSP mismatch is instead being fixed in the documentation, which lists only *.mcl.io while apps/app/src/lib/security-headers.ts in web allows *.mcl.io, wss://*.mcl.io, mcl.spur.us and wss://mcl.spur.us. Documenting all four fixes new installs and breaks nobody. A future SDK move to js.mcl.io can happen once customers have had time to widen their policies.

monocle-backend was never touched: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference.

Reviewer notes

Fixed in this PR: both test scripts now use vitest run, so pnpm test exits instead of hanging in CI.
Fixed in this PR: next ^16.0.0 is a devDependency of monocle-nextjs, so the package builds and typechecks against the newest version its peer range claims, and the CVE-flagged next@15.3.1 (CVE-2025-66478) is out of the lockfile. Dev-only; nothing consumers install changes.

🤖 Generated with Claude Code

Two independent bugs found while testing the PRO-323 AI install prompts against real apps. @spur.us/monocle-nextjs declared next@^13.5.7 || ^14.2.25 || ^15.2.3, so installing into a Next 16 project failed peer resolution outright. The SDK already worked on Next 16 once installed; the range was just stale. @spur.us/monocle-react loaded the script from mcl.spur.us, which does not match the https://*.mcl.io wildcard that docs.spur.us/monocle/security tells customers to allowlist. A CSP is checked against the host being requested, so anyone following those docs had the SDK silently blocked. Both hosts serve byte-identical payloads and mcl.spur.us already CNAMEs to v1.mcl.io, so this is a rename rather than an infrastructure change. monocle-backend keeps BASE_DOMAIN = mcl.spur.us deliberately: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference. Moving that needs the host provisioned first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Anyone currently running the React SDK behind a CSP must have allowlisted mcl.spur.us to get it working, so the upgrade breaks them unless *.mcl.io is allowed too. That belongs at the top of the release note, not buried in the rationale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drops the js.mcl.io rename. Every existing CSP user of this SDK must have allowlisted mcl.spur.us to get it working, so changing the requested host breaks them on update unless they also allow *.mcl.io first. Release notes cannot retroactively update a deployed policy, so no amount of documentation makes the upgrade risk-free. The CSP problem is fixed where it actually belongs: the security docs list only *.mcl.io while the SDK requests mcl.spur.us, so the docs get both hosts. That fixes new installs and breaks nobody. This PR is now the Next 16 peer range alone, which is purely additive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alistairsmith-tech · 2026-08-10T14:41:04Z

@spur.us/monocle-nextjs would not install into a Next 16 project. Found while testing the PRO-323 AI install prompts against a real app.

Part of PRO-349.

The bug

The peer range stopped at ^15.2.3:

- "next": "^13.5.7 || ^14.2.25 || ^15.2.3"+ "next": "^13.5.7 || ^14.2.25 || ^15.2.3 || ^16.0.0"

Next 16.3.0 is current, so npm install @spur.us/monocle-nextjs failed peer resolution outright. No published version, including the 0.5.1 canary, listed Next 16. This blocked the manual onboarding path as much as the AI one, and pushed users toward --legacy-peer-deps or a project-wide .npmrc, both of which have effects well beyond this package.

The SDK already works on Next 16 once installed, so only the range was out of date.

Why this change cannot break anyone

Widening a peer range is purely additive. Consumers on Next 13, 14 and 15 resolve exactly as before, and no runtime code changed. The only behavioural difference is that an install which previously errored now succeeds.

Verified that the combination genuinely works rather than just permitting it:

tsc --noEmit clean against Next 16.3.0
next build succeeds, all 6 pages generated
Dev server boots, homepage 200, loader fires with the publishable key inlined into the client chunk
Range satisfies 15.2.3, 16.0.0, 16.3.0, and correctly rejects 17.0.0
pnpm build and pnpm lint pass across all 5 packages
vitest run passes in monocle-react (7 tests) and monocle-backend (9 tests)

What was deliberately dropped from this PR

An earlier revision also moved the React SDK's loader from mcl.spur.us to js.mcl.io, because the security docs tell customers to allowlist https://*.mcl.io and mcl.spur.us does not match that wildcard.

That has been reverted. Any existing customer running this SDK behind a CSP must have allowlisted mcl.spur.us for it to work at all, so changing the requested host breaks them on update unless they widen their policy first. Release notes cannot retroactively change a deployed CSP, so there is no way to make that rename risk-free for existing users.

The CSP mismatch is instead being fixed in the documentation, which lists only *.mcl.io while apps/app/src/lib/security-headers.ts in web allows *.mcl.io, wss://*.mcl.io, mcl.spur.us and wss://mcl.spur.us. Documenting all four fixes new installs and breaks nobody. A future SDK move to js.mcl.io can happen once customers have had time to widen their policies.

monocle-backend was never touched: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference.

Reviewer notes

Fixed in this PR: both test scripts now use vitest run, so pnpm test exits instead of hanging in CI.
Fixed in this PR: next ^16.0.0 is a devDependency of monocle-nextjs, so the package builds and typechecks against the newest version its peer range claims, and the CVE-flagged next@15.3.1 (CVE-2025-66478) is out of the lockfile. Dev-only; nothing consumers install changes.

🤖 Generated with Claude Code

Two independent bugs found while testing the PRO-323 AI install prompts against real apps. @spur.us/monocle-nextjs declared next@^13.5.7 || ^14.2.25 || ^15.2.3, so installing into a Next 16 project failed peer resolution outright. The SDK already worked on Next 16 once installed; the range was just stale. @spur.us/monocle-react loaded the script from mcl.spur.us, which does not match the https://*.mcl.io wildcard that docs.spur.us/monocle/security tells customers to allowlist. A CSP is checked against the host being requested, so anyone following those docs had the SDK silently blocked. Both hosts serve byte-identical payloads and mcl.spur.us already CNAMEs to v1.mcl.io, so this is a rename rather than an infrastructure change. monocle-backend keeps BASE_DOMAIN = mcl.spur.us deliberately: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference. Moving that needs the host provisioned first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Anyone currently running the React SDK behind a CSP must have allowlisted mcl.spur.us to get it working, so the upgrade breaks them unless *.mcl.io is allowed too. That belongs at the top of the release note, not buried in the rationale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drops the js.mcl.io rename. Every existing CSP user of this SDK must have allowlisted mcl.spur.us to get it working, so changing the requested host breaks them on update unless they also allow *.mcl.io first. Release notes cannot retroactively update a deployed policy, so no amount of documentation makes the upgrade risk-free. The CSP problem is fixed where it actually belongs: the security docs list only *.mcl.io while the SDK requests mcl.spur.us, so the docs get both hosts. That fixes new installs and breaks nobody. This PR is now the Next 16 peer range alone, which is purely additive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alistairsmith-tech · 2026-08-10T14:41:04Z

@spur.us/monocle-nextjs would not install into a Next 16 project. Found while testing the PRO-323 AI install prompts against a real app.

Part of PRO-349.

The bug

The peer range stopped at ^15.2.3:

- "next": "^13.5.7 || ^14.2.25 || ^15.2.3"+ "next": "^13.5.7 || ^14.2.25 || ^15.2.3 || ^16.0.0"

Next 16.3.0 is current, so npm install @spur.us/monocle-nextjs failed peer resolution outright. No published version, including the 0.5.1 canary, listed Next 16. This blocked the manual onboarding path as much as the AI one, and pushed users toward --legacy-peer-deps or a project-wide .npmrc, both of which have effects well beyond this package.

The SDK already works on Next 16 once installed, so only the range was out of date.

Why this change cannot break anyone

Widening a peer range is purely additive. Consumers on Next 13, 14 and 15 resolve exactly as before, and no runtime code changed. The only behavioural difference is that an install which previously errored now succeeds.

Verified that the combination genuinely works rather than just permitting it:

tsc --noEmit clean against Next 16.3.0
next build succeeds, all 6 pages generated
Dev server boots, homepage 200, loader fires with the publishable key inlined into the client chunk
Range satisfies 15.2.3, 16.0.0, 16.3.0, and correctly rejects 17.0.0
pnpm build and pnpm lint pass across all 5 packages
vitest run passes in monocle-react (7 tests) and monocle-backend (9 tests)

What was deliberately dropped from this PR

An earlier revision also moved the React SDK's loader from mcl.spur.us to js.mcl.io, because the security docs tell customers to allowlist https://*.mcl.io and mcl.spur.us does not match that wildcard.

That has been reverted. Any existing customer running this SDK behind a CSP must have allowlisted mcl.spur.us for it to work at all, so changing the requested host breaks them on update unless they widen their policy first. Release notes cannot retroactively change a deployed CSP, so there is no way to make that rename risk-free for existing users.

The CSP mismatch is instead being fixed in the documentation, which lists only *.mcl.io while apps/app/src/lib/security-headers.ts in web allows *.mcl.io, wss://*.mcl.io, mcl.spur.us and wss://mcl.spur.us. Documenting all four fixes new installs and breaks nobody. A future SDK move to js.mcl.io can happen once customers have had time to widen their policies.

monocle-backend was never touched: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference.

Reviewer notes

Fixed in this PR: both test scripts now use vitest run, so pnpm test exits instead of hanging in CI.
Fixed in this PR: next ^16.0.0 is a devDependency of monocle-nextjs, so the package builds and typechecks against the newest version its peer range claims, and the CVE-flagged next@15.3.1 (CVE-2025-66478) is out of the lockfile. Dev-only; nothing consumers install changes.

🤖 Generated with Claude Code

Two independent bugs found while testing the PRO-323 AI install prompts against real apps. @spur.us/monocle-nextjs declared next@^13.5.7 || ^14.2.25 || ^15.2.3, so installing into a Next 16 project failed peer resolution outright. The SDK already worked on Next 16 once installed; the range was just stale. @spur.us/monocle-react loaded the script from mcl.spur.us, which does not match the https://*.mcl.io wildcard that docs.spur.us/monocle/security tells customers to allowlist. A CSP is checked against the host being requested, so anyone following those docs had the SDK silently blocked. Both hosts serve byte-identical payloads and mcl.spur.us already CNAMEs to v1.mcl.io, so this is a rename rather than an infrastructure change. monocle-backend keeps BASE_DOMAIN = mcl.spur.us deliberately: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference. Moving that needs the host provisioned first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Anyone currently running the React SDK behind a CSP must have allowlisted mcl.spur.us to get it working, so the upgrade breaks them unless *.mcl.io is allowed too. That belongs at the top of the release note, not buried in the rationale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drops the js.mcl.io rename. Every existing CSP user of this SDK must have allowlisted mcl.spur.us to get it working, so changing the requested host breaks them on update unless they also allow *.mcl.io first. Release notes cannot retroactively update a deployed policy, so no amount of documentation makes the upgrade risk-free. The CSP problem is fixed where it actually belongs: the security docs list only *.mcl.io while the SDK requests mcl.spur.us, so the docs get both hosts. That fixes new installs and breaks nobody. This PR is now the Next 16 peer range alone, which is purely additive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alistairsmith-tech · 2026-08-10T14:41:04Z

@spur.us/monocle-nextjs would not install into a Next 16 project. Found while testing the PRO-323 AI install prompts against a real app.

Part of PRO-349.

The bug

The peer range stopped at ^15.2.3:

- "next": "^13.5.7 || ^14.2.25 || ^15.2.3"+ "next": "^13.5.7 || ^14.2.25 || ^15.2.3 || ^16.0.0"

Next 16.3.0 is current, so npm install @spur.us/monocle-nextjs failed peer resolution outright. No published version, including the 0.5.1 canary, listed Next 16. This blocked the manual onboarding path as much as the AI one, and pushed users toward --legacy-peer-deps or a project-wide .npmrc, both of which have effects well beyond this package.

The SDK already works on Next 16 once installed, so only the range was out of date.

Why this change cannot break anyone

Widening a peer range is purely additive. Consumers on Next 13, 14 and 15 resolve exactly as before, and no runtime code changed. The only behavioural difference is that an install which previously errored now succeeds.

Verified that the combination genuinely works rather than just permitting it:

tsc --noEmit clean against Next 16.3.0
next build succeeds, all 6 pages generated
Dev server boots, homepage 200, loader fires with the publishable key inlined into the client chunk
Range satisfies 15.2.3, 16.0.0, 16.3.0, and correctly rejects 17.0.0
pnpm build and pnpm lint pass across all 5 packages
vitest run passes in monocle-react (7 tests) and monocle-backend (9 tests)

What was deliberately dropped from this PR

An earlier revision also moved the React SDK's loader from mcl.spur.us to js.mcl.io, because the security docs tell customers to allowlist https://*.mcl.io and mcl.spur.us does not match that wildcard.

That has been reverted. Any existing customer running this SDK behind a CSP must have allowlisted mcl.spur.us for it to work at all, so changing the requested host breaks them on update unless they widen their policy first. Release notes cannot retroactively change a deployed CSP, so there is no way to make that rename risk-free for existing users.

The CSP mismatch is instead being fixed in the documentation, which lists only *.mcl.io while apps/app/src/lib/security-headers.ts in web allows *.mcl.io, wss://*.mcl.io, mcl.spur.us and wss://mcl.spur.us. Documenting all four fixes new installs and breaks nobody. A future SDK move to js.mcl.io can happen once customers have had time to widen their policies.

monocle-backend was never touched: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference.

Reviewer notes

Fixed in this PR: both test scripts now use vitest run, so pnpm test exits instead of hanging in CI.
Fixed in this PR: next ^16.0.0 is a devDependency of monocle-nextjs, so the package builds and typechecks against the newest version its peer range claims, and the CVE-flagged next@15.3.1 (CVE-2025-66478) is out of the lockfile. Dev-only; nothing consumers install changes.

🤖 Generated with Claude Code

Two independent bugs found while testing the PRO-323 AI install prompts against real apps. @spur.us/monocle-nextjs declared next@^13.5.7 || ^14.2.25 || ^15.2.3, so installing into a Next 16 project failed peer resolution outright. The SDK already worked on Next 16 once installed; the range was just stale. @spur.us/monocle-react loaded the script from mcl.spur.us, which does not match the https://*.mcl.io wildcard that docs.spur.us/monocle/security tells customers to allowlist. A CSP is checked against the host being requested, so anyone following those docs had the SDK silently blocked. Both hosts serve byte-identical payloads and mcl.spur.us already CNAMEs to v1.mcl.io, so this is a rename rather than an infrastructure change. monocle-backend keeps BASE_DOMAIN = mcl.spur.us deliberately: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference. Moving that needs the host provisioned first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Anyone currently running the React SDK behind a CSP must have allowlisted mcl.spur.us to get it working, so the upgrade breaks them unless *.mcl.io is allowed too. That belongs at the top of the release note, not buried in the rationale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drops the js.mcl.io rename. Every existing CSP user of this SDK must have allowlisted mcl.spur.us to get it working, so changing the requested host breaks them on update unless they also allow *.mcl.io first. Release notes cannot retroactively update a deployed policy, so no amount of documentation makes the upgrade risk-free. The CSP problem is fixed where it actually belongs: the security docs list only *.mcl.io while the SDK requests mcl.spur.us, so the docs get both hosts. That fixes new installs and breaks nobody. This PR is now the Next 16 peer range alone, which is purely additive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alistairsmith-tech · 2026-08-10T14:41:04Z

@spur.us/monocle-nextjs would not install into a Next 16 project. Found while testing the PRO-323 AI install prompts against a real app.

Part of PRO-349.

The bug

The peer range stopped at ^15.2.3:

- "next": "^13.5.7 || ^14.2.25 || ^15.2.3"+ "next": "^13.5.7 || ^14.2.25 || ^15.2.3 || ^16.0.0"

Next 16.3.0 is current, so npm install @spur.us/monocle-nextjs failed peer resolution outright. No published version, including the 0.5.1 canary, listed Next 16. This blocked the manual onboarding path as much as the AI one, and pushed users toward --legacy-peer-deps or a project-wide .npmrc, both of which have effects well beyond this package.

The SDK already works on Next 16 once installed, so only the range was out of date.

Why this change cannot break anyone

Widening a peer range is purely additive. Consumers on Next 13, 14 and 15 resolve exactly as before, and no runtime code changed. The only behavioural difference is that an install which previously errored now succeeds.

Verified that the combination genuinely works rather than just permitting it:

tsc --noEmit clean against Next 16.3.0
next build succeeds, all 6 pages generated
Dev server boots, homepage 200, loader fires with the publishable key inlined into the client chunk
Range satisfies 15.2.3, 16.0.0, 16.3.0, and correctly rejects 17.0.0
pnpm build and pnpm lint pass across all 5 packages
vitest run passes in monocle-react (7 tests) and monocle-backend (9 tests)

What was deliberately dropped from this PR

An earlier revision also moved the React SDK's loader from mcl.spur.us to js.mcl.io, because the security docs tell customers to allowlist https://*.mcl.io and mcl.spur.us does not match that wildcard.

That has been reverted. Any existing customer running this SDK behind a CSP must have allowlisted mcl.spur.us for it to work at all, so changing the requested host breaks them on update unless they widen their policy first. Release notes cannot retroactively change a deployed CSP, so there is no way to make that rename risk-free for existing users.

The CSP mismatch is instead being fixed in the documentation, which lists only *.mcl.io while apps/app/src/lib/security-headers.ts in web allows *.mcl.io, wss://*.mcl.io, mcl.spur.us and wss://mcl.spur.us. Documenting all four fixes new installs and breaks nobody. A future SDK move to js.mcl.io can happen once customers have had time to widen their policies.

monocle-backend was never touched: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference.

Reviewer notes

Fixed in this PR: both test scripts now use vitest run, so pnpm test exits instead of hanging in CI.
Fixed in this PR: next ^16.0.0 is a devDependency of monocle-nextjs, so the package builds and typechecks against the newest version its peer range claims, and the CVE-flagged next@15.3.1 (CVE-2025-66478) is out of the lockfile. Dev-only; nothing consumers install changes.

🤖 Generated with Claude Code

Two independent bugs found while testing the PRO-323 AI install prompts against real apps. @spur.us/monocle-nextjs declared next@^13.5.7 || ^14.2.25 || ^15.2.3, so installing into a Next 16 project failed peer resolution outright. The SDK already worked on Next 16 once installed; the range was just stale. @spur.us/monocle-react loaded the script from mcl.spur.us, which does not match the https://*.mcl.io wildcard that docs.spur.us/monocle/security tells customers to allowlist. A CSP is checked against the host being requested, so anyone following those docs had the SDK silently blocked. Both hosts serve byte-identical payloads and mcl.spur.us already CNAMEs to v1.mcl.io, so this is a rename rather than an infrastructure change. monocle-backend keeps BASE_DOMAIN = mcl.spur.us deliberately: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference. Moving that needs the host provisioned first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Anyone currently running the React SDK behind a CSP must have allowlisted mcl.spur.us to get it working, so the upgrade breaks them unless *.mcl.io is allowed too. That belongs at the top of the release note, not buried in the rationale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drops the js.mcl.io rename. Every existing CSP user of this SDK must have allowlisted mcl.spur.us to get it working, so changing the requested host breaks them on update unless they also allow *.mcl.io first. Release notes cannot retroactively update a deployed policy, so no amount of documentation makes the upgrade risk-free. The CSP problem is fixed where it actually belongs: the security docs list only *.mcl.io while the SDK requests mcl.spur.us, so the docs get both hosts. That fixes new installs and breaks nobody. This PR is now the Next 16 peer range alone, which is purely additive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alistairsmith-tech · 2026-08-10T14:41:04Z

@spur.us/monocle-nextjs would not install into a Next 16 project. Found while testing the PRO-323 AI install prompts against a real app.

Part of PRO-349.

The bug

The peer range stopped at ^15.2.3:

- "next": "^13.5.7 || ^14.2.25 || ^15.2.3"+ "next": "^13.5.7 || ^14.2.25 || ^15.2.3 || ^16.0.0"

Next 16.3.0 is current, so npm install @spur.us/monocle-nextjs failed peer resolution outright. No published version, including the 0.5.1 canary, listed Next 16. This blocked the manual onboarding path as much as the AI one, and pushed users toward --legacy-peer-deps or a project-wide .npmrc, both of which have effects well beyond this package.

The SDK already works on Next 16 once installed, so only the range was out of date.

Why this change cannot break anyone

Widening a peer range is purely additive. Consumers on Next 13, 14 and 15 resolve exactly as before, and no runtime code changed. The only behavioural difference is that an install which previously errored now succeeds.

Verified that the combination genuinely works rather than just permitting it:

tsc --noEmit clean against Next 16.3.0
next build succeeds, all 6 pages generated
Dev server boots, homepage 200, loader fires with the publishable key inlined into the client chunk
Range satisfies 15.2.3, 16.0.0, 16.3.0, and correctly rejects 17.0.0
pnpm build and pnpm lint pass across all 5 packages
vitest run passes in monocle-react (7 tests) and monocle-backend (9 tests)

What was deliberately dropped from this PR

An earlier revision also moved the React SDK's loader from mcl.spur.us to js.mcl.io, because the security docs tell customers to allowlist https://*.mcl.io and mcl.spur.us does not match that wildcard.

That has been reverted. Any existing customer running this SDK behind a CSP must have allowlisted mcl.spur.us for it to work at all, so changing the requested host breaks them on update unless they widen their policy first. Release notes cannot retroactively change a deployed CSP, so there is no way to make that rename risk-free for existing users.

The CSP mismatch is instead being fixed in the documentation, which lists only *.mcl.io while apps/app/src/lib/security-headers.ts in web allows *.mcl.io, wss://*.mcl.io, mcl.spur.us and wss://mcl.spur.us. Documenting all four fixes new installs and breaks nobody. A future SDK move to js.mcl.io can happen once customers have had time to widen their policies.

monocle-backend was never touched: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference.

Reviewer notes

Fixed in this PR: both test scripts now use vitest run, so pnpm test exits instead of hanging in CI.
Fixed in this PR: next ^16.0.0 is a devDependency of monocle-nextjs, so the package builds and typechecks against the newest version its peer range claims, and the CVE-flagged next@15.3.1 (CVE-2025-66478) is out of the lockfile. Dev-only; nothing consumers install changes.

🤖 Generated with Claude Code

Two independent bugs found while testing the PRO-323 AI install prompts against real apps. @spur.us/monocle-nextjs declared next@^13.5.7 || ^14.2.25 || ^15.2.3, so installing into a Next 16 project failed peer resolution outright. The SDK already worked on Next 16 once installed; the range was just stale. @spur.us/monocle-react loaded the script from mcl.spur.us, which does not match the https://*.mcl.io wildcard that docs.spur.us/monocle/security tells customers to allowlist. A CSP is checked against the host being requested, so anyone following those docs had the SDK silently blocked. Both hosts serve byte-identical payloads and mcl.spur.us already CNAMEs to v1.mcl.io, so this is a rename rather than an infrastructure change. monocle-backend keeps BASE_DOMAIN = mcl.spur.us deliberately: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference. Moving that needs the host provisioned first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Anyone currently running the React SDK behind a CSP must have allowlisted mcl.spur.us to get it working, so the upgrade breaks them unless *.mcl.io is allowed too. That belongs at the top of the release note, not buried in the rationale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drops the js.mcl.io rename. Every existing CSP user of this SDK must have allowlisted mcl.spur.us to get it working, so changing the requested host breaks them on update unless they also allow *.mcl.io first. Release notes cannot retroactively update a deployed policy, so no amount of documentation makes the upgrade risk-free. The CSP problem is fixed where it actually belongs: the security docs list only *.mcl.io while the SDK requests mcl.spur.us, so the docs get both hosts. That fixes new installs and breaks nobody. This PR is now the Next 16 peer range alone, which is purely additive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alistairsmith-tech · 2026-08-10T14:41:04Z

@spur.us/monocle-nextjs would not install into a Next 16 project. Found while testing the PRO-323 AI install prompts against a real app.

Part of PRO-349.

The bug

The peer range stopped at ^15.2.3:

- "next": "^13.5.7 || ^14.2.25 || ^15.2.3"+ "next": "^13.5.7 || ^14.2.25 || ^15.2.3 || ^16.0.0"

Next 16.3.0 is current, so npm install @spur.us/monocle-nextjs failed peer resolution outright. No published version, including the 0.5.1 canary, listed Next 16. This blocked the manual onboarding path as much as the AI one, and pushed users toward --legacy-peer-deps or a project-wide .npmrc, both of which have effects well beyond this package.

The SDK already works on Next 16 once installed, so only the range was out of date.

Why this change cannot break anyone

Widening a peer range is purely additive. Consumers on Next 13, 14 and 15 resolve exactly as before, and no runtime code changed. The only behavioural difference is that an install which previously errored now succeeds.

Verified that the combination genuinely works rather than just permitting it:

tsc --noEmit clean against Next 16.3.0
next build succeeds, all 6 pages generated
Dev server boots, homepage 200, loader fires with the publishable key inlined into the client chunk
Range satisfies 15.2.3, 16.0.0, 16.3.0, and correctly rejects 17.0.0
pnpm build and pnpm lint pass across all 5 packages
vitest run passes in monocle-react (7 tests) and monocle-backend (9 tests)

What was deliberately dropped from this PR

An earlier revision also moved the React SDK's loader from mcl.spur.us to js.mcl.io, because the security docs tell customers to allowlist https://*.mcl.io and mcl.spur.us does not match that wildcard.

That has been reverted. Any existing customer running this SDK behind a CSP must have allowlisted mcl.spur.us for it to work at all, so changing the requested host breaks them on update unless they widen their policy first. Release notes cannot retroactively change a deployed CSP, so there is no way to make that rename risk-free for existing users.

The CSP mismatch is instead being fixed in the documentation, which lists only *.mcl.io while apps/app/src/lib/security-headers.ts in web allows *.mcl.io, wss://*.mcl.io, mcl.spur.us and wss://mcl.spur.us. Documenting all four fixes new installs and breaks nobody. A future SDK move to js.mcl.io can happen once customers have had time to widen their policies.

monocle-backend was never touched: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference.

Reviewer notes

Fixed in this PR: both test scripts now use vitest run, so pnpm test exits instead of hanging in CI.
Fixed in this PR: next ^16.0.0 is a devDependency of monocle-nextjs, so the package builds and typechecks against the newest version its peer range claims, and the CVE-flagged next@15.3.1 (CVE-2025-66478) is out of the lockfile. Dev-only; nothing consumers install changes.

🤖 Generated with Claude Code

Two independent bugs found while testing the PRO-323 AI install prompts against real apps. @spur.us/monocle-nextjs declared next@^13.5.7 || ^14.2.25 || ^15.2.3, so installing into a Next 16 project failed peer resolution outright. The SDK already worked on Next 16 once installed; the range was just stale. @spur.us/monocle-react loaded the script from mcl.spur.us, which does not match the https://*.mcl.io wildcard that docs.spur.us/monocle/security tells customers to allowlist. A CSP is checked against the host being requested, so anyone following those docs had the SDK silently blocked. Both hosts serve byte-identical payloads and mcl.spur.us already CNAMEs to v1.mcl.io, so this is a rename rather than an infrastructure change. monocle-backend keeps BASE_DOMAIN = mcl.spur.us deliberately: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference. Moving that needs the host provisioned first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Anyone currently running the React SDK behind a CSP must have allowlisted mcl.spur.us to get it working, so the upgrade breaks them unless *.mcl.io is allowed too. That belongs at the top of the release note, not buried in the rationale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drops the js.mcl.io rename. Every existing CSP user of this SDK must have allowlisted mcl.spur.us to get it working, so changing the requested host breaks them on update unless they also allow *.mcl.io first. Release notes cannot retroactively update a deployed policy, so no amount of documentation makes the upgrade risk-free. The CSP problem is fixed where it actually belongs: the security docs list only *.mcl.io while the SDK requests mcl.spur.us, so the docs get both hosts. That fixes new installs and breaks nobody. This PR is now the Next 16 peer range alone, which is purely additive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alistairsmith-tech · 2026-08-10T14:41:04Z

@spur.us/monocle-nextjs would not install into a Next 16 project. Found while testing the PRO-323 AI install prompts against a real app.

Part of PRO-349.

The bug

The peer range stopped at ^15.2.3:

- "next": "^13.5.7 || ^14.2.25 || ^15.2.3"+ "next": "^13.5.7 || ^14.2.25 || ^15.2.3 || ^16.0.0"

Next 16.3.0 is current, so npm install @spur.us/monocle-nextjs failed peer resolution outright. No published version, including the 0.5.1 canary, listed Next 16. This blocked the manual onboarding path as much as the AI one, and pushed users toward --legacy-peer-deps or a project-wide .npmrc, both of which have effects well beyond this package.

The SDK already works on Next 16 once installed, so only the range was out of date.

Why this change cannot break anyone

Widening a peer range is purely additive. Consumers on Next 13, 14 and 15 resolve exactly as before, and no runtime code changed. The only behavioural difference is that an install which previously errored now succeeds.

Verified that the combination genuinely works rather than just permitting it:

tsc --noEmit clean against Next 16.3.0
next build succeeds, all 6 pages generated
Dev server boots, homepage 200, loader fires with the publishable key inlined into the client chunk
Range satisfies 15.2.3, 16.0.0, 16.3.0, and correctly rejects 17.0.0
pnpm build and pnpm lint pass across all 5 packages
vitest run passes in monocle-react (7 tests) and monocle-backend (9 tests)

What was deliberately dropped from this PR

An earlier revision also moved the React SDK's loader from mcl.spur.us to js.mcl.io, because the security docs tell customers to allowlist https://*.mcl.io and mcl.spur.us does not match that wildcard.

That has been reverted. Any existing customer running this SDK behind a CSP must have allowlisted mcl.spur.us for it to work at all, so changing the requested host breaks them on update unless they widen their policy first. Release notes cannot retroactively change a deployed CSP, so there is no way to make that rename risk-free for existing users.

The CSP mismatch is instead being fixed in the documentation, which lists only *.mcl.io while apps/app/src/lib/security-headers.ts in web allows *.mcl.io, wss://*.mcl.io, mcl.spur.us and wss://mcl.spur.us. Documenting all four fixes new installs and breaks nobody. A future SDK move to js.mcl.io can happen once customers have had time to widen their policies.

monocle-backend was never touched: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference.

Reviewer notes

Fixed in this PR: both test scripts now use vitest run, so pnpm test exits instead of hanging in CI.
Fixed in this PR: next ^16.0.0 is a devDependency of monocle-nextjs, so the package builds and typechecks against the newest version its peer range claims, and the CVE-flagged next@15.3.1 (CVE-2025-66478) is out of the lockfile. Dev-only; nothing consumers install changes.

🤖 Generated with Claude Code

Two independent bugs found while testing the PRO-323 AI install prompts against real apps. @spur.us/monocle-nextjs declared next@^13.5.7 || ^14.2.25 || ^15.2.3, so installing into a Next 16 project failed peer resolution outright. The SDK already worked on Next 16 once installed; the range was just stale. @spur.us/monocle-react loaded the script from mcl.spur.us, which does not match the https://*.mcl.io wildcard that docs.spur.us/monocle/security tells customers to allowlist. A CSP is checked against the host being requested, so anyone following those docs had the SDK silently blocked. Both hosts serve byte-identical payloads and mcl.spur.us already CNAMEs to v1.mcl.io, so this is a rename rather than an infrastructure change. monocle-backend keeps BASE_DOMAIN = mcl.spur.us deliberately: it builds https://decrypt.${baseDomain}, decrypt.mcl.io has no DNS record, and decrypt.mcl.spur.us is what the decryption docs reference. Moving that needs the host provisioned first. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Anyone currently running the React SDK behind a CSP must have allowlisted mcl.spur.us to get it working, so the upgrade breaks them unless *.mcl.io is allowed too. That belongs at the top of the release note, not buried in the rationale. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drops the js.mcl.io rename. Every existing CSP user of this SDK must have allowlisted mcl.spur.us to get it working, so changing the requested host breaks them on update unless they also allow *.mcl.io first. Release notes cannot retroactively update a deployed policy, so no amount of documentation makes the upgrade risk-free. The CSP problem is fixed where it actually belongs: the security docs list only *.mcl.io while the SDK requests mcl.spur.us, so the docs get both hosts. That fixes new installs and breaks nobody. This PR is now the Next 16 peer range alone, which is purely additive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alistairsmith-tech requested a review from benperkins August 10, 2026 14:41

benperkins previously approved these changes Aug 10, 2026
View reviewed changes

alistairsmith-tech dismissed benperkins’s stale review via 5fc8c61August 10, 2026 19:30

alistairsmith-tech changed the title ~~fix(PRO-349): support Next 16 and load the browser SDK from js.mcl.io~~fix(PRO-349): accept Next 16 as a peer dependencyAug 10, 2026

benperkins approved these changes Aug 10, 2026
View reviewed changes

alistairsmith-tech merged commit c37895d into mainAug 10, 2026
5 checks passed

alistairsmith-tech deleted the fix/pro-349 branch August 10, 2026 19:52