visibility design and discussion by mighdoll · Pull Request #187 · webgpu-tools/wesl-spec

mighdoll · 2026-05-12T21:29:29Z

TLDR

Module visibility. Three levels: public (visible to any package),
private (declaring module only), and package (same package, the unmarked
default).
Re-exports. public import re-exports the imported names under the
current module's path; public import path::* does the same for a wildcard
(re-uses @wildcardable diagnostics).
Host pipeline visibility. The link's root module defines the host-visible
API: entry points, resource variables, and pipeline-overridable constants
reach the host only if the root module declares them or public imports them.
package.wesl. The file backing a package's top-level module, so its
items are reachable as <package>::item (e.g., import wgsl_test::*). One
place a library can put a re-export prelude.

Why these four things are covered:

module visibility is needed for re-exports
re-exports are needed for wildcards
pipeline visibility works best integrated with the module visibility design
package.wesl is so that we can write e.g., import wgsl_test::*;

(Note that VisibilityLanguages.md is discussion background, it'll be removed before merging.)

Would resolve:

#65 @publish import
#98 allow private marking
#28 public by default (closed)
#130 wildcards
(largely covered already; this PR fills in the re-export piece)
PR #62 comment for lib.wesl

With wildcard re-exports, resolving an import means looking through a set of modules recursively to find the right item. And since modules can have cycles, one now needs to keep track of which modules have been visited during import resolution. In the language server, this is a fair amount of extra complexity.

This particular feature also, I believe, interacts really badly with macros or other compile time code generation. Rust's import system ends up being a very complex fixed point finding algorithm which may sometimes simply fail.

(I think it also interacts with parameterized modules. Since wildcard reexports is the missing piece to make import statements recursive. If imports can cause any sort of computations, which compile time generated code does, and which parameterized modules do, then one gets the halting problem. Or so the story goes.)

Usually I wouldn't object to complexity too much.
In this case, I did want to point it out, since wildcard re-exports enables nothing new. It is a very rarely used feature and I could always manually write it out.

mighdoll · 2026-05-14T00:05:11Z

Personally I don't have a strong opinion either way, but there is lots of prior art for the second option (most JS package systems, Python, Rust, Lua)

while I can't think of anything that has this strict root/non-root separation off the top of my head.

Not sure, always interesting to look around tho!

Here I was only filling the gap where our current scheme doesn't allow something at the root level. I think small libraries especially might like to enable their users to my_pkg::foo(); or import wgsl_test::*; without adding an extra path level.

It'd be a separate issue, but your comments about consistency... I suppose we could revise the existing rules so that X::X.wesl always flattens the contents to X::. package::package.wesl flattens to package::. lygia::math::math.wesl flattens to lygia::math, etc.

mighdoll · 2026-05-14T00:07:09Z

Also quick and very inconvenient note: private is somehow not a reserved WGSL word.

wat!? good catch. Perhaps @public @private. I think we'll want to ask the WGSL committee too.

mighdoll · 2026-05-14T00:57:12Z

Usually I wouldn't object to complexity too much.
In this case, I did want to point it out, since wildcard re-exports enables nothing new. It is a very rarely used feature and I could always manually write it out.

Worth thinking about. I like the idea of implementing the needed features w/o gilding the lily too much.

The cycles/complexity concerns seem heavy for a feature that isn't must-have. And foreclosing options for parameterized modules would be unfortunate.

Also I realize that the PR doesn't address some related issues:

what if there's a latent collision between wildcard re-exports in a library? That would be something we'd want to catch at publish time, not wait for clients to use the library and find an error.
what happens if you wildcard re-export from a module with wildcard imports?

I'm thinking best would be to pull wildcard re-exports from this PR.

Side note, if we go with the publish tool route as planned with #183, I suppose we could also expand wildcard re-exports like we're planning for wildcard imports. That would help for the cross package cases.

mighdoll · 2026-05-14T05:43:02Z

pushed a draft

@public and @private
wildcard re-exports deferred

stefnotch · 2026-05-15T16:35:21Z

We could also go with

pub, priv
public, protected (Rust does not have a private keyword, upside of private by default)

Also, what does private mean? Rust goes all in on the hierarchical module system and says

If an item is private, it may be accessed by the current module and its descendants.
https://doc.rust-lang.org/reference/visibility-and-privacy.html

mighdoll · 2026-05-15T17:05:49Z

* `pub`, `priv`

I like this option too, a bit more cryptic but if perhaps best if we prefer keywords to attributes.

* `public`, `protected`

I like public clear and readable. I fear confusion around protected - it has a contrary meaning in other languages visibility systems.

I suppose we could do public and priv..

Also, what does private mean? Rust goes all in on the hierarchical module system

just the module, no hierarchy. we could expand hierarchically later, it's a nice idea. But I think of most WESL programs as smallish, so perhaps unnecessary complexity, better to defer.

stefnotch · 2026-05-15T17:38:32Z

For the public, protected option, I was trying to suggest having the following visibility modifiers

public (keyword)
protected (keyword)
private (the default, thus does not need a keyword)

mighdoll · 2026-05-15T19:25:10Z

* `private` (the default, thus does not need a keyword)

Ah, that was my first instinct too. I like modularity. But I've come to think that package by default for WESL is better. See Why package by default? in the design discussion doc. package by default is low ceremony for most projects, and works better for wgsl compat at the root module..

stefnotch · 2026-05-17T17:50:26Z

Also interesting tidbit:
Rust allows for two different styles of visibility. One is a local and hierarchical style, where I only use public and private. And I apply that to both items and modules. A internal (protected) item is modeled by having a public item inside a private module.

The other style is the global style, where I use 3 access modifiers. Public, internal (protected) and private.

And apparently some of the very prolific Rust contributors, including epage who maintains a bunch of extremely well written libraries, vastly prefer the global style. So we are on the right track!

https://www.reddit.com/r/rust/comments/1k5yv6p/two_ways_of_interpreting_visibility_in_rust/

stefnotch · 2026-05-17T18:06:15Z

More from Rust land:
The reasons for why they went with private by default for fields is to allow for local reasoning and

Visibility is often how soundness is achieved for many types in rust.
https://rust-lang.github.io/rfcs/0001-private-fields.html

They also include statistics which says that private is more common than public.

stefnotch · 2026-05-17T18:08:44Z

And from Kotlin lang: They went with public by default, only to realize that it might have been a mistake. So defaulting to a more restrictive choice like "internal" seems wise

https://kotlinlang.org/docs/api-guidelines-simplicity.html

stefnotch · 2026-05-17T23:00:41Z

Note from Java:
Java's default is actually somewhat similar to Rust. In Java, a "package" corresponds to a folder. And classes are visible within a package by default.

stefnotch · 2026-05-18T07:28:48Z

We really should ask the WGSL committee regarding the private keyword. Would you like to do the honors?

stefnotch · 2026-05-18T09:44:26Z

I dug into it and asked the WebGPU commitee gpuweb/gpuweb#6264

I couldn't quite figure out where it got lost though. It seems to have happened quite a while ago, judging from Naga's source code

stefnotch · 2026-05-19T17:31:48Z

I talked to a friend regarding this. priv would be a weird choice. As much as it pains me to say this, I would prefer private as a context sensitive keyword over priv.

Fixes to wesl.toml

replace the left-to-right segment walk with direct resolution: the last path segment names the declared item, the preceding segments name the module. declarations and modules naturally live in separate namespaces now - `fn foo() {}` and `foo::bar();` do not conflict lazy vs eager resolution is an implementation choice clarify terms a bit

Conflict resolution per 193-into-187 merge checklist: - keep the public import re-export paragraph in the grammar section; take direct-imports' module attribute wording - replace the old import walk algorithm with the new 'Resolving a declaration path' model from direct-imports - reattach public import re-exports to item lookup in the new resolution section - carry over the resolution-vs-visibility paragraph and the wildcard visibility-skip rule after the resolution rules - point Filesystem Resolution at the new resolution section - keep the Visibility.md re-exports link in the wildcardable recommendations Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add wildcard imports

- describe super:: flattening early, so resolution later can be clearer - write package module generically w/o being fs specific - drop wesl.toml mini-section (we have a whole page on it now) - Cleanup fs resolution section logic for direct imports - Add brief section on non-fs resolution

- demote the "tools can enumerate resolutions" paragraph to a [!NOTE] - clarify intermediate paths don't need to be modules

direct import resolution (more editorial fixes coming with #187)

- tighten visibility terminology and scope the summary table - clarify root selection, static access, and defaulted override behavior - explaine rationale for root module determines pipeline visible API - correct WGSL terminology and the @!wildcardable example - sharpen the rationale for visibility levels, syntax, and deferred extensions

stefnotch · 2026-07-14T13:29:23Z

I am happy with this direction. A proper review will come later.
I do still think private-by-default might be a better trade-off, but there's nothing strong backing it up at the moment.

So my preferred option would be reviewing and merging this. Afterwards we create a draft proposal for private-by-default, to explore what that would imply. For example, a truly good private-by-default proposal would likely involve extending the createShaderModule API on the host side.

And the other thing that I'd like to explore is: What is the most common visibility in any given project.
I am thinking of the Bevy game engine in particular. That question can be answered once we have a fully Bevy-WESL. In fact, the language server more or less should have all the relevant info, since it will gain the "find all references" capability at some point.

Edit: We talked about this today, the strongest signal will simply be observing what our users do. For example, if people start writing private everywhere out of paranoia, then we'll have to tweak the design. Meanwhile if people mostly rely on internal being convenient, then the current design is good.
Also, Bevy is a unique project, because its scope is so much larger.

mighdoll · 2026-07-14T16:47:41Z

I am happy with this direction.
So my preferred option would be reviewing and merging this.

We should feel good about the direction, knowing that we can course correct while the language and community are young.

For example, a truly good private-by-default proposal would likely involve extending the createShaderModule API on the host side.

Right that's a hurdle, e.g. for potential upstreaming into WGSL.

I am thinking of the Bevy game engine in particular.

Yeah, having something for Bevy was the original motivation for this. In general visibility control is important for libraries. Also presuming that we don't end up with public by default, we'll either break compatibility or commit to dealing with maintaining migration capability in the tools. So good to get something in soon while there's little to break. More recently, I've realized I would like to use visibility soon for the wgsl-play stuff too (e.g., to make clean root modules via re-exports).

And the other thing that I'd like to explore is: What is the most common visibility in any given project.

Just noting we want to look at a breadth of projects / use cases. The design goal I think about most often is how to keep things simple for the common / new user, while enabling power features for the sophisticated.

k2d222

Looking good! a bunch of editorial and nitpicks comments, otherwise there is just one thing I want to defend: re-exporting package-visible declarations, see the comment about Lygia.

Also, make it clear to readers that app users need not to worry about public it's a good selling point of the design!

k2d222 · 2026-07-15T13:50:42Z

+import my_lib::prelude::*;       // wildcard pulls all of the above
+```
+
+A bare `import` brings names into local scope without re-exporting them.


editorial: with a private visibility. i.e. it behaves like a private local declaration.

tried a fix in the latest draft (tho different wording w/o the private analogy)

k2d222 · 2026-07-15T14:13:19Z

+declarations in the root module and follows references transitively.
+
+An `import` statement is not itself a static access. An imported item is
+statically accessed when an identifier referring to it appears in a body, type,


editorial: ...appears in a statically accessed body... or attribute of a statically accessed declaration.

revised in latest draft

k2d222 · 2026-07-15T14:15:56Z

+initializer, or attribute.
+
+Pipeline-visible items keep their exposed names in the linked WGSL output. A
+root-declared item keeps its declared name. An item re-exported by `public


editorial: line jump messes up formatting

revised in latest draft

k2d222 · 2026-07-15T15:03:11Z

+it. A wildcard import omits items that are not visible to the importer. A name
+collision between two wildcard imports is therefore an error only when both
+items are visible (see [Wildcard imports](Imports.md#wildcard-imports)).
+


we should also reference that fact in wildcard-imports

k2d222 · 2026-07-15T15:39:54Z

+Naming a less-visible type in a `public` signature or field is permitted with no
+diagnostic.
+
+## Re-exports


can you re-export from "parent" modules? sounds like an anti-pattern, but I'm not sure.

Nothing stops it, agree seems likely bad style, good for a linter rule.

k2d222 · 2026-07-16T10:37:44Z

Cf. #202 (comment), We should treat this case in the spec:

private struct foo { ... }
public alias bar = foo; // is bar public? can I access its fields?

I think i this case bar should be public but be an opaque type.

mighdoll · 2026-07-17T05:15:03Z

I think in this case bar should be public but be an opaque type.

Good one. I agree we'll want something so that APIs can return structs with hidden internal details. I think it deserves its own issue. Filed #204.

private struct foo { ... }
public alias bar = foo; // is bar public? can I access its fields?

I'll update to make the alias an error in this PR while we consider what we want in #204. WGSL alias semantics say that aliases don't create new types. Should they create new visibility? Maybe, but there are other approaches to opaqueness that I suspect we'll like better..

k2d222 · 2026-07-17T12:42:03Z

+An alias whose target resolves through any chain of aliases to a declared
+structure type must not be more visible than the structure declaration. A WGSL
+alias introduces another name for the same type and preserves its value
+constructors and members. A more-visible alias would therefore make the type
+nameable and constructible outside its visibility boundary (see
+[A re-export cannot widen visibility](#a-re-export-cannot-widen-visibility)).
+The visibility of an intermediate alias does not constrain a later alias. For
+example, `public alias Shared = Local;` is permitted when `Local` is a
+*package*-visible alias for a `public` structure type.


I'm not 100% sure this is the best solution here, but we can keep it this way for now. In -rs, the 1st implementation iteration will probably allow public aliases to private structs, because checking the spec rule is harder.

sounds like a good plan. It's a corner case that few users will notice. #202 and #204 should give us some more clarity on visibility widening and opaque views of types, and then we can then adjust the alias rule and the fn signature rules about less visible types consistently.

stefnotch

I found an edge case that we'll have to test.

// in foo.wesl
public import package::utils as GetUtils; // a module

// in package.wesl
import package::foo::GetUtils;

const a = GetUtils::SOME_CONST;

If I do it correctly, I first expand to

const a = package::foo::GetUtils::SOME_CONST;

and then I resolve.

If I do it as a two step process, I might do the incorrect

// resolves to package::utils
import package::foo::GetUtils;

// so this resolves to 
const a = package::utils::SOME_CONST;

We should add that to the testsuite. And I'll have to be careful in wgsl-analyzer. W-a currently purposefully tries to do it as a two step process so that we can detect errors earlier.

stefnotch · 2026-07-18T21:49:47Z

+// sun_intensity not in the pipeline-visible API: host cannot set it; uses its default of 1.0
+```
+
+### Aggregating entry points


I wonder if we could design an even neater world if we start messing with the host APIs. Like "any entrypoint in any module that is public can be used, the host API just has to say which one it wants"

stefnotch · 2026-07-18T21:51:08Z

I approve of shipping this and implementing it. There's no reason to block further progress on small comments.

If we come up with significantly better solutions, we can always ship a new iteration of the spec.

Fix #178

23c1c0b

Fix #175

github-project-automation Bot added this to specs and docs May 12, 2026

github-project-automation Bot moved this to Todo in specs and docs May 12, 2026

mighdoll requested review from k2d222 and stefnotch May 12, 2026 23:48

visibility design and discussion

2be5aa7

mighdoll force-pushed the visibility branch from fcf4a29 to 2be5aa7 Compare May 13, 2026 01:41

rename org references: wgsl-tooling-wg -> webgpu-tools

9fc3471

mighdoll mentioned this pull request May 13, 2026

importing from single function modules is a little verbose.. #128

Open

mighdoll added 2 commits May 13, 2026 22:33

syntax to @public / @Private

75ec680

defer wildcard re-exports to future work

21f610d

Merge pull request #182 from webgpu-tools/fix-wesl-toml

6f68abc

Fixes to wesl.toml

mighdoll mentioned this pull request Jun 24, 2026

Bevy has multiple crates #189

Open

mighdoll and others added 7 commits July 2, 2026 19:18

merge in updates from wildcard-imports PR #183

6460f61

Merge pull request #183 from webgpu-tools/glob-imports

7c642e9

Add wildcard imports

Merge remote-tracking branch 'refs/remotes/origin/main' into visibility

5cff896

address k2d222 comments on #199:

9a381df

- demote the "tools can enumerate resolutions" paragraph to a [!NOTE] - clarify intermediate paths don't need to be modules

mighdoll mentioned this pull request Jul 8, 2026

direct import resolution #199

Merged

mighdoll added a commit that referenced this pull request Jul 8, 2026

Merge pull request #199 from webgpu-tools/direct-imports

f7714ea

direct import resolution (more editorial fixes coming with #187)

k2d222 requested changes Jul 15, 2026

View reviewed changes

k2d222 mentioned this pull request Jul 16, 2026

Module Visibility control #202

Open

mighdoll added 2 commits July 16, 2026 22:03

address k2d222 comments, misc cleanups

9502218

drop reviewer-only languages survey

e59decc

mighdoll mentioned this pull request Jul 17, 2026

Member visibility (opaque structs) #204

Open

k2d222 reviewed Jul 17, 2026

View reviewed changes

k2d222 approved these changes Jul 17, 2026

View reviewed changes

mighdoll added 2 commits July 18, 2026 13:42

formatting

d59c82c

private resources and entry points are errors

2950ba6

stefnotch reviewed Jul 18, 2026

View reviewed changes

mighdoll merged commit c39b4cc into glob-imports Jul 19, 2026
1 check passed

github-project-automation Bot moved this from Todo to Done in specs and docs Jul 19, 2026

Uh oh!

Conversation

mighdoll commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Would resolve:

Related

Uh oh!

s-ol commented May 13, 2026

Uh oh!

stefnotch commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefnotch commented May 13, 2026

Uh oh!

stefnotch commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mighdoll commented May 14, 2026

Uh oh!

mighdoll commented May 14, 2026

Uh oh!

mighdoll commented May 14, 2026

Uh oh!

mighdoll commented May 14, 2026

Uh oh!

stefnotch commented May 15, 2026

Uh oh!

mighdoll commented May 15, 2026

Uh oh!

stefnotch commented May 15, 2026

Uh oh!

mighdoll commented May 15, 2026

Uh oh!

stefnotch commented May 17, 2026

Uh oh!

stefnotch commented May 17, 2026

Uh oh!

stefnotch commented May 17, 2026

Uh oh!

stefnotch commented May 17, 2026

Uh oh!

stefnotch commented May 18, 2026

Uh oh!

stefnotch commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefnotch commented May 19, 2026

Uh oh!

stefnotch commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mighdoll commented Jul 14, 2026

Uh oh!

k2d222 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k2d222 commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

mighdoll commented May 12, 2026 •

edited

Loading

stefnotch commented May 13, 2026 •

edited

Loading

stefnotch commented May 13, 2026 •

edited

Loading

stefnotch commented May 18, 2026 •

edited

Loading

stefnotch commented Jul 14, 2026 •

edited

Loading

k2d222 commented Jul 16, 2026 •

edited

Loading