Evaluate proposed restructuring of browser

[VisLab]

@claude Right now the browser/ directory holds both the api documentation and an online validator. We are thinking of separating the online validator into a separate repository. The existing browser directory would become a docs directory with the API and a user guide. The online validator would be moved to a separate repository where it would install the new hed-validator as a dependency. Analyze this code carefully and determine whether this could be done simply by separating the two parts or whether it would require additional infrastructure or significant changes in the hed-validator. Ultimately we might like to have additional browser operations besides dataset and events file validation. Make a plan for us and indicate issues that you spot.

[VisLab]

@claude Right now the browser/ directory holds both the api documentation and an online validator. We are thinking of separating the online validator into a separate repository. The existing browser directory would become a docs directory with the API and a user guide. The online validator would be moved to a separate repository where it would install the new hed-validator as a dependency. Analyze this code carefully and determine whether this could be done simply by separating the two parts or whether it would require additional infrastructure or significant changes in the hed-validator. Ultimately we might like to have additional browser operations besides dataset and events file validation. Make a plan for us and indicate issues that you spot.

[github-actions]

Claude finished @VisLab's task in 4m 55s —— View job

---

Analysis: Restructuring browser/ Directory

Tasks:

• Explore browser/ directory structure
• Analyze API docs portion
• Analyze online validator portion
• Identify dependencies and coupling between the two parts
• Identify required changes to hed-validator for separation
• Assess extensibility for additional browser operations
• Write final plan with identified issues

---

Current Structure

The browser/ directory is a multi-page Vite/React application that currently serves two purposes:

Part	Files	Purpose
API Docs	docs/html/ (generated by typedoc)	Developer reference — copied to buildweb/docs/ at build time
Online Validator	index.html, validate_dataset.html, validate_file.html, src/	Interactive browser-based HED validator

The two are linked at runtime via a nav card in NavOptions.jsx (line 34: href: './docs/'), but there is no code coupling between them — the docs are purely static HTML.

---

Separation Feasibility

The good news: The docs and validator are already logically separated. The only connection is that vite.config.js copies docs/html/ into the build output as a post-build step (lines 77–92). Splitting them apart is conceptually straightforward.

The complication: The online validator currently depends on private internal APIs of hed-javascript that are not exported through the public index.js entry point. Moving the validator to a separate repo that installs hed-validator as an npm dependency would require either exporting those APIs or rewriting the parts that use them.

---

Specific Internal API Dependencies

Here is every place the browser validator reaches into src/ directly instead of using the public package API:

1. browser/src/schema/init.js — biggest issue

This file is essentially a private copy of src/schema/init.js, modified to use a browser-compatible schema loader. It directly imports:

• SchemaParser from src/schema/parser — not exported
• PartneredSchemaMerger from src/schema/schemaMerger — not exported
• Schema, Schemas from src/schema/containers — not exported
• setParent from src/utils/xml.js — not exported
• splitStringTrimAndRemoveBlanks from src/utils/string — not exported
• SchemasSpec from src/schema/specs — not exported

The root cause is that the public buildSchemasFromVersion (exported from index.js) uses the Node.js file-system schema loader and won't work in a browser. The browser code works around this by re-implementing the entire schema building pipeline with a Vite-bundled loader.

2. browser/src/schema/loader.js

Uses parseSchemaXML from src/utils/xml.js — not exported.

3. browser/src/schema/vite-importer.js

export const schemaData = import.meta.glob('../../../src/data/schemas/*.xml', { query: '?raw', import: 'default' })

This uses Vite's import.meta.glob to bundle all schema XML files from the source tree at build time. In a separate repo, there would be no source tree to glob from.

4. browser/src/bids/BidsWebAccessor.js

• Imports BidsFileAccessor from src/bids/datasetParser.js — ✓ already exported via index.js
• Imports BidsHedIssue from src/bids/types/issues.js — ✓ already exported

5. browser/src/validate_file.jsx

• Imports parseTSV from src/bids/tsvParser.js — not exported

6. Various direct path aliases

vite.config.js defines @hed-javascript-root pointing to the repo root, and files use this alias to access internal modules. In a separate repo this alias would have nowhere to point.

---

What Would Need to Change in hed-validator

To support a standalone online validator repo that depends on hed-validator as an npm package, the following additions are needed:

Change	Effort	Notes
Export parseTSV	Low	Simple re-export in index.js
Export a browser-compatible buildSchemasFromVersion	Medium	The main blocker. Options below.
Export bundled schema XML data	Medium	Schemas are already inlined in the ESM dist via esbuild; they just need to be accessible
Remove or shim @hed-javascript-root alias	Low	Handled in new repo's vite.config.js

Schema loading options (pick one):

• Option A — buildSchemasFromVersion with browser support (recommended): Add a conditional export path in package.json (the "browser" field or a new "exports" condition). The browser entry would use a loader that reads schema data from the bundled ESM package rather than from disk. Since esbuild.mjs already bundles XML schemas inline (via loader: { '.xml': 'text' }), this data is available in dist/esm/ — it just needs a public accessor.

• Option B — Ship schemas as JSON/assets: Publish a schemas/ directory as part of the npm package. The online validator fetches the needed schema version from there. This is the lowest-risk change to hed-validator itself.

• Option C — Remote-only schema loading: Remove bundled schema support and always fetch from GitHub raw URLs. Already partially supported in loader.js (loadRemoteSchema). Simpler but adds latency and a network dependency.

---

Deployment & Infrastructure Changes

Current deployment (deploy-pages.yml):

1. Checks out hed-javascript
2. Runs npm run build (builds hed-validator)
3. npm link — links the local dev build to the browser subproject
4. Builds docs with typedoc
5. Vite build copies docs + schemas into buildweb/
6. Deploys buildweb/ to GitHub Pages

After separation:

Repo	GitHub Pages	Build Steps
hed-javascript (→ docs/)	Yes — deploys docs/html/	Run typedoc, upload artifact
New hed-online-validator	Yes — deploys Vite build output	Install hed-validator from npm, run Vite build

The npm link trick goes away — the online validator would simply install the published package. This creates a versioning dependency: the online validator repo must pin (or track) a specific hed-validator version. This is manageable but needs a release process (e.g., the online validator's workflow pins a specific version, or uses latest).

---

Issues Spotted

1. limitErrors state is unused in validate_file.jsx (line 26): The comment // This state is not used by performHedValidation yet confirms it's a dead code path. It's read from state but never actually passed to the validation logic.

2. Schema loading architecture mismatch: The fact that browser/src/schema/init.js is a near-duplicate of src/schema/init.js is a design smell. If buildSchemasFromVersion were browser-compatible, this duplication would disappear. The separation is a good opportunity to fix this properly.

3. vite-importer.js is Vite-specific and tightly coupled to source tree layout. The import.meta.glob with a 3-level-up relative path (../../../src/data/schemas/) would break in any environment where the schemas aren't at that exact relative location. This is the primary technical obstacle to separation.

4. The browser/ project has no hed-validator listed as a dependency in package.json. It relies on npm link to find it. A standalone repo would need this declared properly ("hed-validator": "^4.x.x" in package.json), which also means hed-validator must be published to npm before the online validator can be deployed.

5. vite.config.js hardcodes the base path as /hed-javascript/ (line 21). In a new repo this would need to change to the new repo name, or be made configurable via an env variable.

6. Content Security Policy in index.html (line 9) allows connect-src 'self' https://raw.githubusercontent.com. This is fine for remote schema loading but would need to be revisited if the schema loading strategy changes.

7. BidsWebAccessor.js import uses a relative path ('../../../src/bids/datasetParser.js') instead of the alias (@hed-javascript-root). After separation, this would need to change to import from the hed-validator package instead.

---

Recommended Plan

Phase 1 — Prepare hed-validator (in this repo)

• Export parseTSV from index.js
• Design and implement a browser-compatible buildSchemasFromVersion (or a loadSchemaXml primitive that the online validator can use without duplicating the build pipeline)
• Add a "browser" conditional export to package.json pointing to a browser-safe entry point, or expose schema data through the public API
• Document which APIs the online validator is expected to use (prevents accidental breakage)

Phase 2 — Set up new hed-online-validator repo

• Copy browser/src/ into the new repo (most files move as-is)
• Replace @hed-javascript-root alias with real hed-validator package imports in vite.config.js
• Rewrite vite-importer.js / schema loading to use the public package API (no import.meta.glob on the source tree)
• Rewrite or remove browser/src/schema/init.js (use the public buildSchemasFromVersion)
• Add hed-validator as a proper npm dependency
• Create GitHub Actions workflow for build + GitHub Pages deploy
• Update vite.config.js base path for the new repo name

Phase 3 — Clean up hed-javascript

• Move/rename browser/ → docs/ (or keep API docs under docs/ only)
• Simplify deploy-pages.yml to just build and deploy typedoc output
• Remove Vite/React build infrastructure from this repo (unless kept for future use)

Phase 4 — Future operations
The architecture (multi-page Vite/React app + NavOptions.jsx nav cards) is well-suited for extension. Each new browser operation would add:

• A new <operation>.html entry point
• A new <operation>.jsx page component
• A new entry in NavOptions.jsx
• Any new hed-validator API surface needed (exposed via the package)

The only prerequisite is that whatever new operation is needed must be expressible using the public hed-validator API. This is a good forcing function to keep the public API complete and browser-compatible.

---

Bottom line: The separation is feasible and not architecturally complex, but it is not a simple copy-paste. The primary work is in Phase 1 — making hed-validator expose a browser-compatible schema loading API so the online validator doesn't need to reach into private internals. Once that is done, Phases 2 and 3 are largely mechanical.