fix: migrate Drupal presets to @helixui/tokens@3.x

[himerus]

v0.9.3 — Wire @helixui/tokens@3.x into the Drupal scaffold

v0.9.2 left every Drupal preset pinned to @helixui/tokens@^0.2.0 with carve-outs in doctor + upgrade because the Drupal preset surface wasn't verified against 3.x. Investigating that work for v0.9.3 surfaced a deeper latent bug: the Drupal scaffold had always declared @helixui/tokens as a dependency but never loaded its CSS, so every var(--hx-*, fallback) reference resolved to its inline fallback instead of the upstream brand token.

What changed for fresh Drupal scaffolds

• Real runtime wiring. {theme}.libraries.yml now declares a helix-tokens library that loads css/vendor/helix-tokens.css at weight: -200, and global depends on it. Tokens are in the cascade before any theme CSS that references them.
• Build-time-bundled tokens.css for deterministic output. scripts/add-shebang.mjs runs at every create-helix build and copies @helixui/tokens/dist/tokens.css → dist/assets/helix-tokens.css. scaffoldDrupalTheme reads that bundled copy at scaffold time and writes it into the theme's css/vendor/helix-tokens.css. Two consequences:
  • Scaffold output is deterministic per create-helix version — the same release always emits the same bytes, independent of how the installer's npm/pnpm/yarn resolves transitive deps.
  • Wiring activates immediately on cp -r theme/ + drush theme:enable — the documented Drupal setup, which doesn't run npm install.
• Postinstall script as the refresh path. scripts/copy-helix-tokens.mjs runs on npm install and re-vendors from whatever @helixui/tokens resolves in the theme's own tree. Resolved via createRequire + require.resolve of the package's exported CSS subpaths (not ./package.json, which @helixui/tokens@3.x's exports map doesn't publish — that throws ERR_PACKAGE_PATH_NOT_EXPORTED). Works in hoisted/workspace installs.
• Modernized token references. generateStyleCss now uses --hx-body-font-family / --hx-body-color / --hx-body-bg / --hx-body-line-height (3.x's semantic body tokens — the pre-3.x --hx-font-family-base etc. don't exist in 3.x). generateHelixOverridesCss examples and the generated README customization snippet were updated to reference 3.x token names (--hx-color-primary-500, --hx-color-surface-default, --hx-color-surface-raised, etc.) so a user who uncomments them actually gets values that take effect.
• Single load path for the token layer. css/style.css no longer @imports vendor/helix-tokens.css — the library system's global → helix-tokens dependency loads it instead, avoiding duplicate fetch/parse on every page.
• Centralized version pin. src/presets/loader.ts now imports HELIX_TOKENS_VERSION, joining every framework template on the same pin. create-helix's own @helixui/tokens dep is bumped to ^3.9.1 and both lockfiles refreshed so the build-time bundling picks up 3.9.1 bytes.

Existing (pre-v0.9.3) Drupal scaffolds — explicitly deferred to v0.9.4

doctor and upgrade continue to exempt @helixui/tokens for any project declaring @helixui/drupal-starter. The runtime token layer for a Drupal theme is css/vendor/helix-tokens.css, NOT the declared range. Bumping the pin alone (without also rewriting that vendored CSS plus, for pre-v0.9.3 themes, injecting the missing wiring files) would advance the declaration while the theme keeps serving stale bytes — a dishonest remediation. Task #86 makes runUpgrade Drupal-theme-aware: re-vendor the CSS at upgrade time and, for pre-v0.9.3 themes, inject the wiring. At that point both skips drop.

Verification

• npm run verify (lint + format + type-check) — clean
• Full test suite — 3256 passing, 8 pre-existing skips (+9 new tests for the wiring, the build-time bundling, the conditional skips, and the new override doc-comments)
• All 5 Drupal preset integration suites green (standard, blog, healthcare, intranet, ecommerce)
• Reviewed clean by the codex push-gate (0 findings)

Release

Patch — create-helix@0.9.3. Changeset included.