Add new Addon(url) and deprecate existing addon APIs - #172
Merged
Conversation
kasperisager
force-pushed
the
deprecate-addon-apis
branch
from
August 3, 2026 11:51
8a3b2a1 to
a3a057a
Compare
tony-go
approved these changes
Aug 3, 2026
| constructor(url) { | ||
| const { protocol } = url | ||
|
|
||
| if (protocol !== 'builtin:' && protocol !== 'linked:' && protocol !== 'file:') { |
There was a problem hiding this comment.
I wonder if we could not have a protocols array as we did for conditions and extensions.
Contributor
Author
There was a problem hiding this comment.
The branch predictor should have an easy time with this so I'd favor the explicit checks, since there's only 3, over a set.has() call.
lucas-tortora
added a commit
to holepunchto/pear-docs
that referenced
this pull request
Aug 6, 2026
…read docs runtime.mdx still described Addon.load()/.resolve()/.cache and Thread.create() as the current way to do things. holepunchto/bare#172 (in v1.31.0, already inside our tracked window) added a new `new Addon(url)` constructor and deprecated those four members — a real, user-facing change the first pass at this page's <Since> markers missed. Root cause, not just the content: most of that commit's npm/index.d.ts diff was Bare.Addon/Bare.Thread becoming top-level siblings (a harmless namespace merge), and the genuine addition (`Addon.constructor`) got lumped in with that cosmetic rename on review — its giveaway was having no matching removal, easy to miss by eye. Independently, bare-model-surface.ts's fingerprint never read `BareExport.deprecated` at all, so the four newly-deprecated members produced literally zero diff output, not just an easy-to-miss one. Fixed both: `deprecated` is now a first-class fingerprinted field (surfaces as "newly deprecated" on a changed member, and as "(deprecated)" even on a renamed one that shows up as a plain addition), and runtime.mdx's Addon/ Thread sections now describe `new Addon(url)` as current with <Since v="1.31.0" /> and flag the four deprecated members inline. Co-Authored-By: Claude <noreply@anthropic.com>
lucas-tortora
added a commit
to holepunchto/pear-docs
that referenced
this pull request
Aug 7, 2026
* feat(docs): version the Bare CLI, runtime API, and Kit reference pages Extends the Pear platform version dropdown (<Since>/<Until>/<VersionSection>, ?v= filtering) to the three Bare platform pages, generalizing the previously Pear-only isPlatformPath()/DOCS_VERSIONS into a multi-axis registry (src/lib/version-axes.ts). Pear's own dropdown is unchanged. Three independent dropdowns, not one shared "Bare version": bare-cli and bare-runtime both ship from holepunchto/bare but are tracked as separate surfaces; bare-kit tracks the separately-versioned holepunchto/react-native-bare-kit, the only repo with a canonical .d.ts for the Worklet API. scripts/gen-bare-docs-states.ts derives each axis's doc-state list from real upstream diffs — reusing bare-refgen/extract.ts's TS Compiler API walker for bare-runtime/bare-kit (both have a clean .d.ts), and a new paparam extractor (scripts/bare-cli-surface.ts) for bare-cli, which has none. Wired into the existing upstream-releases.yml workflow as a report-only step, matching the repo's established rule that a new doc-state needs a human to author the matching content markers. Co-Authored-By: Claude <noreply@anthropic.com> * feat(bare-refs): pin upstreamVersion frontmatter on generated bare-* module pages Threads the already-resolved package version (fetchPackage()'s pkg.version, which already flowed into scripts/bare-refgen/versions.json) into each rendered page's frontmatter as upstreamVersion — one line, no prose touched. Unblocks check-upstream-pins.ts, which already scans content/reference/bare but had nothing to grade: unpinned count drops from 40 to 9 (6 modules ship no upstream .d.ts to pin against; the 3 platform pages intentionally use the version-dropdown axis instead of a frontmatter pin). Regenerated via `gen:bare-refs -- --write` against all 70 currently-live bare-* modules (the default top-10-by-downloads selection would have missed the rest). Per-major real URLs for a future major bump are a separate, larger follow-up, not built here. Co-Authored-By: Claude <noreply@anthropic.com> * fix(docs): make deprecation a fingerprinted field, fix stale Addon/Thread docs runtime.mdx still described Addon.load()/.resolve()/.cache and Thread.create() as the current way to do things. holepunchto/bare#172 (in v1.31.0, already inside our tracked window) added a new `new Addon(url)` constructor and deprecated those four members — a real, user-facing change the first pass at this page's <Since> markers missed. Root cause, not just the content: most of that commit's npm/index.d.ts diff was Bare.Addon/Bare.Thread becoming top-level siblings (a harmless namespace merge), and the genuine addition (`Addon.constructor`) got lumped in with that cosmetic rename on review — its giveaway was having no matching removal, easy to miss by eye. Independently, bare-model-surface.ts's fingerprint never read `BareExport.deprecated` at all, so the four newly-deprecated members produced literally zero diff output, not just an easy-to-miss one. Fixed both: `deprecated` is now a first-class fingerprinted field (surfaces as "newly deprecated" on a changed member, and as "(deprecated)" even on a renamed one that shows up as a plain addition), and runtime.mdx's Addon/ Thread sections now describe `new Addon(url)` as current with <Since v="1.31.0" /> and flag the four deprecated members inline. Co-Authored-By: Claude <noreply@anthropic.com> * fix(docs): document missing Worklet constructor overload, wakeup, update Auditing bare-kit.mdx against react-native-bare-kit's current index.d.ts (prompted by finding the same class of gap in runtime.mdx) turned up three real omissions, none related to deprecation this time — none of these symbols have ever been marked @deprecated: - `new Worklet(id, options)` — the second constructor overload, added in v0.10.5 (verified against the tag), never documented. Added with <Since v="0.10.5" />. - `wakeup([deadline])` — an instance method present since the oldest tag in our tracked window (v0.9.0), omitted from the Actions list even though its sibling lifecycle methods (suspend/resume/terminate) were all there. - `update(state)` — same story: present since v0.9.0, never documented. - Noted (not documented as instance actions, since Worklet.host-level static variants are a distinct capability): suspend/resume/wakeup/update are also static methods, driving every worklet at once. Since these three predate our whole 5-doc-state tracked window, no <Since> marker applies to wakeup/update — they're just gaps, not version deltas. Co-Authored-By: Claude <noreply@anthropic.com> * fix(docs): use <Until> not <Since> for the deprecation badges (wrong color) <Since> is hardwired to green (BADGE_COLORS.since, "added" semantics) — the label prop only overrides the TEXT, not which color variant renders. Using <Since label="Deprecated in 1.31.0" /> displayed a deprecation warning in the same green normally used to celebrate a new feature, sending the opposite visual signal from what the text said. <Until> already has precedent for a non-removal label override (cli.mdx's "Fixed in 3.1.0") and renders in the cautionary yellow that actually matches "deprecated." Verified the computed background is #f0e57a post-fix (was #7dde9a). No visibility/gating change — both markers are childless annotations, never hidden either way. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
3 tasks
lucas-tortora
added a commit
to holepunchto/pear-docs
that referenced
this pull request
Aug 7, 2026
#346) Every existing staleness check in this repo only notices a TAGGED release (check-upstream-releases.ts, check-upstream-pins.ts, gen-bare-docs-states.ts). A real API change can sit on a default branch for however long it takes upstream to cut one — exactly the gap that let holepunchto/bare#172's deprecations go unnoticed until manually caught. This adds a finer-grained layer underneath all of them: has the latest commit touching each watched repo's SOURCE-OF-TRUTH FILE moved since we last looked, scoped to a single file's commit history (via GitHub's ?path= filter) so 86 watched repos don't turn into noise from unrelated commits. scripts/resolve-upstream-commits-config.ts (one-time, re-run only when the watched module list changes) resolves and VERIFIES — never assumes — each repo's real default branch and its most-authoritative file, prioritizing a shipped .d.ts when one exists (mirrors bare-refgen/fetch.ts's own resolution order exactly) and falling back to the real entry source file otherwise. Sourced from data already on disk: generated/bare-refs/*/api-model.json's cached repoUrl for the 70 bare-* modules, scripts/refgen/repos.ts for the 12 building-blocks/helpers repos, plus the 3 Bare platform axes and Pear's CLI. All 86 entries resolved clean, including catching a real non-"main" default branch (bare-prom-client uses `bareify`) that a hardcoded assumption would have silently gotten wrong. scripts/check-upstream-commits.ts is the daily job: compares each entry's latest commit-for-path against a committed state file, reports drift grouped by .d.ts (prioritized, higher-confidence) vs. other, and — verified against a real backdated entry — correctly re-detects the exact e70e82d commit from the previous fix. Same advisory contract as every other check here: `--check` never writes state, so a change keeps showing in the daily summary until a human reviews it and runs the write form locally — silent self-clearing would turn a missed day into a missed change forever. Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This deprecates
Addon.cache,Addon.resolve(), andAddon.load()in favor of anew Addon(url)API that exclusively handles loading, leaving caching and resolution entirely to the user-space module system.