docs: document plugins + sync #66/#67 docs; fix contributed-prop override typing#68
Merged
bigmistqke merged 5 commits intoJun 6, 2026
Conversation
…y#66 rewrite The source-agnostic pointer rewrite (solidjs-community#66) shipped without updating the docs, leaving two pages describing an API that no longer exists: - events/overview: drop the `onMouse*` family (removed in solidjs-community#66 — only `onPointer*`/`onClick`/`onWheel` remain) from the supported, stoppable, and non-stoppable lists and the event-applicability table. - utilities/raycasters: `EventRaycaster` adds `cast(registry, context)`, not the deleted `update(event, context)`. Rewrite the interface, the custom-raycaster example (subclass `CursorRaycaster`/override `setCursor`), and document `ScreenRaycaster` and `ControllerRaycaster`.
…ur chapter solidjs-community#67 shipped the plugin system without docs. Add both halves: - API reference (utilities/plugin): what a plugin is, the three plugin() forms, registration via createT and <Entity plugins>, and the typed contributed-prop guarantee. - Tour chapter 09 "Plugins": builds a lookAt plugin from the "props set properties, not call methods" motivation, ending in a live demo — a field of cones that turn to face the pointer (verified in-browser). Insert it before the WebGPU peek (renumbered 09 -> 10 so the peek stays the finale) and retarget chapter 08's closing handoff.
… deps) The <Demo> editor and three are all behind dynamic imports / optimizeDeps.exclude, so vite didn't see them at startup — it discovered them on first demo mount, re-optimized, and forced a full page reload mid-session (and ran the 1MB three.module.js through vite-plugin-solid's Babel on the way). Pre-bundle the editor stack (@bigmistqke/repl, tm-textarea/solid, and its transitive @bigmistqke/solid-whenever + @solid-primitives/resize-observer) and move three from exclude to include, so the optimize cost is paid once at startup and three skips the Babel transform. optimizeDeps is dev-only — the production build is unaffected.
A Mesh's lookAt() points +Z at the target (three swaps eye/target for non-camera objects; only cameras/lights aim -Z). Rotate the cone tip onto +Z so the tips point at the cursor, not away. Verified in-browser.
A plugin intercepts its prop at runtime (applyProp checks pluginMethods first), so a contributed prop should be able to reuse a native member's name — e.g. a `lookAt` plugin driving `Object3D.lookAt`. But `Props` intersected the contributed type with the base, yielding `nativeMethod & V`, which no value satisfies (`<T.Mesh lookAt={vec}/>` failed to type-check).
Drop the contributed keys from `BaseProps` before adding the contributed props, so the contributed type replaces the native one — matching the runtime. Guarded for the no-plugins case: the loose default `readonly Plugin[]` has `length: number`, so `keyof PluginPropsOf` would be every key; yield `never` (drop nothing) unless a real tuple of plugins is inferred. The inference-critical second half stays a direct `Partial<PluginPropsOf<…>>`.
bigmistqke
changed the title
commit: |
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
1 participant
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.
Summary
The #66 events rewrite and the #67 plugin system both shipped without their doc updates — the site was describing an API that no longer exists and a feature that was never documented. This clears that debt, adds an interactive plugins tour chapter, and fixes one plugin-typing bug the demo surfaced.
Stale docs corrected (#66)
events/overview— drops theonMouse*family (removed in refactor(events)!: source-agnostic pointer system (Pointer + EventRaycaster + DOMPointerManager) #66; onlyonPointer*/onClick/onWheelremain) from the supported, stoppable, and non-stoppable lists and the event-applicability table.utilities/raycasters— the page documentedEventRaycaster.update(event, context), which refactor(events)!: source-agnostic pointer system (Pointer + EventRaycaster + DOMPointerManager) #66 deleted. Rewritten around the realcast(registry, context)interface, with a corrected custom-raycaster example and new sections forScreenRaycasterandControllerRaycaster.Plugins documented (#67)
utilities/plugin— new API page: what a plugin is, the threeplugin()forms (global / class-filtered / type-guard), registration viacreateTand<Entity plugins>, and the typed contributed-prop guarantee.lookAtplugin from the "props set properties, they don't call methods" motivation, ending in a live demo: a field of cones that turn to face the pointer. Inserted before the WebGPU peek (renumbered 09 → 10 so the peek stays the finale); chapter 08's close now hands off to it.Library fix: contributed props override native members
Writing the
lookAtdemo surfaced a bug in the #67 plugin typing. A plugin intercepts its prop at runtime (applyPropcheckspluginMethodsfirst), so a contributed prop should be able to reuse a native member's name — e.g.lookAtdrivingObject3D.lookAt. ButPropsintersected the contributed type with the base, producingnativeMethod & V, which no value satisfies, so<T.Mesh lookAt={vec} />failed to type-check even though it worked at runtime.Propsnow drops the contributed keys fromBasePropsbefore adding them, so the contributed type replaces the native one — matching the runtime. Guarded so the common no-plugins case is untouched (the loose defaultreadonly Plugin[]haslength: number; only a real inferred tuple contributes override keys). Regression test added. This is what lets the tour demo use the naturallookAtprop name.Test plan
pnpm build+pnpm lint(circular + eslint + types) green.Vector3is assignable to a contributedlookAtprop.optimizeDeps.includechange.