Restructure hooks docs

[Rich-Harris]

Describe the problem

The naming around hooks files is a bit weird:

• hooks.server.ts contains server and 'shared' hooks
• hooks.client.ts contains client and 'shared' hooks
• hooks.ts contains 'universal' hooks

'Shared' doesn't mean shared, it means that the hooks in question (init and handleError) can have two separate implementations for server and client. The 'universal' hooks (reroute and transport) are, however, shared.

Describe the proposed solution

Not for nothing, this is more aesthetically appealing:

hooks.client.ts
hooks.server.ts
hooks.shared.ts

hooks.shared.ts would contain what are today called 'universal' hooks but which are actually shared between server and client.

Docs-wise I would get rid of the 'Server hooks', 'Shared hooks' and 'Universal hooks' headings in favour of the hooks themselves, each of which would have something like this right after the heading:

## handle

> [!NOTE] Declared in `hooks.server.ts`

## init

> [!NOTE] Declared in `hooks.server.ts` and `hooks.client.ts`

## reroute

> [!NOTE] Declared in `hooks.shared.ts`

Alternatives considered

No response

Importance

nice to have

Additional Information

No response

[Nic-Polumeyv]

Unsuffixed already means "runs in both environments" everywhere else. +page.ts vs +page.server.ts, $lib/foo.ts vs $lib/foo.server.ts, and the load docs call these universal under a heading literally titled "Universal vs server". After the rename the same concept is universal in one doc and shared in another, the same drift this issue is fixing, just moved between pages. It also introduces a .shared. suffix that exists nowhere else in kit, while .server. has real tooling behind it now (#16266). The "Declared in" notes fix the confusion on their own, and if a rename is still wanted, hooks.universal.ts at least matches the established term, though its ugliness kind of suggests the rename is the wrong half of the proposal.

Curious whether you see hooks as a special case because it's the only three file family, or whether the longer term direction is explicit suffixes everywhere. If it's the former, is shared doing something universal wouldn't?

[Nic-Polumeyv]

Related: #11537, where hooks.js got its name and the shared-vs-universal confusion first came up.

[Rich-Harris]

Fair points. We decided that this wasn't worth the churn, so we don't implement it, but I'll leave the issue open for the docs change (using hook names instead of category for the h2s)

[Nic-Polumeyv]

Glad the docs made it out alive. You just have beef with every kit file name at this point 😄