Share the Finder UI between the PWA and the ClassicStack SPA

[pgodwin]

This branch turns ClassicStack-web from a standalone PWA into the shared Finder UI for two different applications: this PWA, and the admin SPA served by ClassicStack (Go). One Finder window, one set of dialogs, one catalog model — two very different backends underneath.

How the sharing works

ClassicStack consumes this repo as a git submodule and aliases it straight to source — there is no npm publish and no intermediate build artifact:

# ClassicStack/third_party/README.md
git submodule add https://github.com/ObsoleteMadness/ClassicStack-web.git third_party/classicstack-web

// ClassicStack/adapter/control/http/ui/vite.config.ts
'classicstack-web': path.join(webRoot, 'src'),

// ClassicStack/adapter/control/http/ui/tsconfig.json
"classicstack-web/*": ["../../../../third_party/classicstack-web/src/*"]

package.json exports declares the public surface (~60 entry points: ui/*, finder/*, fs/*, protocol/*, services/*, transport/*). Both apps typecheck against the same TypeScript sources, so a break in the contract surfaces in CI on both sides rather than at runtime.

The seam: FinderHost

The Finder window knows nothing about AFP, HTTP, or Web Serial. Everything backend-shaped goes through one protocol-neutral interface (src/ui/finder-host.ts) — discover, login, mount, catalog:

graph TD
    subgraph shared["ClassicStack-web/src — shared source"]
        FW["ui/finder-window<br/>dialogs · menus · Get Info<br/>resource explorers"]
        FH{{"ui/finder-host<br/>FinderHost contract"}}
        CAT["fs/catalog-caps<br/>NodeRef · VolumeIdentity<br/>CatalogCapabilities"]
        FW --> FH
        FW --> CAT
    end

    FH -.implemented by.-> AH["AfpFinderHost<br/>(this PWA)"]
    FH -.implemented by.-> GH["GoFinderHost<br/>(ClassicStack SPA)"]

    AH --> AFP["Web Serial → TashTalk → LocalTalk<br/>in-browser AFP client<br/><b>session lives in the browser</b>"]
    GH --> HTTP["HTTP → Go server<br/>AFP · SMB · NCP · EtherDFS<br/><b>session lives server-side</b>"]

Loading

	PWA (AfpFinderHost)	SPA (GoFinderHost)
Transport	Web Serial → TashTalk → LocalTalk	fetch → Go control API
Protocol stack	In-browser: DDP/ATP/ASP/AFP	Server-side: AFP, SMB, NCP, EtherDFS
Session state	In the browser tab	On the server
Catalog	RemoteVfs over the AFP client	HttpCatalog over the control API

The SPA imports ~27 modules across this seam today — ui/finder-window, ui/finder-host, the login / alert / name-conflict dialogs, the File and View menus, Get Info, the Mac and Windows resource explorers, the extension editor, finder/api-catalog, finder/types, fs/catalog-caps, fs/extension-map, util/prefs.

What's in the branch

• Protocol-neutral FinderHost so the Go SPA can reuse the Finder UI, with hosts owning sidebar groups, badges, context menus, and per-group network scans — the window renders, the host decides.
• Catalog capabilities — NodeRef, VolumeIdentity and per-backend CatalogCapabilities (AFP, SMB, NCP, EtherDFS, local share), re-exported from finder/index as the shared public contract. This unblocks ClassicStack's CI, which already imported NodeRef, CatalogCapabilities, and classicstack-web/ui/settings-icons before they had ever left this working tree.
• Multiple open servers at once, plus a Settings window.
• Finder menus — File and View split out of the window with shared shortcut rendering.
• Windows resource tools — PE/NE icon extraction and a Windows resource explorer, alongside the existing Mac resource fork explorer.
• Zip export, a pluggable extension-editor store, and a Macintosh codec registry so SIT and rez stay replaceable.

The regression this also fixes

Sharing one Finder across two session models is exactly where the last commit's bug came from. Opening a share always failed with FPOpenVol UserNotAuth (-5023). A LocalTalk pcap shows the client throwing away its own login:

pkt
56	FPLogin — succeeds
61	FPGetSrvrParms — volumes listed
73	FPLogout ← client discards the authenticated session
78	CloseSession
87	OpenSession — fresh, unauthenticated
92	FPOpenVol BlueSCSI Mac Plus
97	-5023 user not authenticated

connectServerWithLogin has a fast path for endpoints already in loggedInEndpoints: it calls beginRemote purely to refresh the server name and volume list, then mounts the volume without logging in again. That is correct against GoFinderHost, where the session lives on the server and beginRemote is a cheap query. Against AfpFinderHost the session lives in the browser, so beginRemote's unconditional close() logged it out — opening any share after signing in always failed.

Fixes:

• afp-finder-host: beginRemote reuses a live authenticated session for the same endpoint instead of tearing it down, and reports the volumes it already knows rather than a hardcoded empty list. beginRemote is now idempotent on both hosts, which is what the shared caller assumed all along.
• finder-window: only overwrite knownVolumes when beginRemote returns a non-empty list — the hardcoded [] was wiping the cached volume list on every fast-path connect, leaving the sidebar showing just the one volume being opened.
• finder-window: a failed mount now drops the cached login and falls through to the sign-in loop, so a session the server timed out no longer leaves the share unopenable until the user disconnects by hand.
• New afp-finder-host.test.ts covering session reuse, title-vs-id endpoint matching, and both reconnect cases.

The general lesson for this seam: anything the shared Finder calls speculatively to refresh state has to be safe to call on a host that keeps real, stateful connections behind it.

Testing

npx tsc --noEmit clean; npx vitest run — 55 files, 384 passed, 1 skipped.

The -5023 path was reproduced against a real Mac over LocalTalk and verified against the pcap; the rest of the branch is covered by the existing suite.

Follow-up after merge

ClassicStack/third_party/README.md currently pins the submodule to feature/shared-finder-host, and make spa falls back to a sibling ../ClassicStack-web checkout or clones WEB_REF (default feature/shared-finder-host). Both want to move to main once this lands.

🤖 Generated with Claude Code