@crombolo/backoffice-host 0.0.0-stage → 0.9.1

package/src/graphics.ts

@@ -0,0 +1,87 @@
+/**
+ * The login/back-office branding images. These live on Umbraco's
+ * BackOfficeGraphicsController, which is excluded from the OpenAPI document, so
+ * they cannot be routed through the contract-first router.
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { MANAGEMENT_API_PATH } from '@crombolo/core'
+import type { BackOfficePaths } from './paths.ts'
+
+export const GRAPHICS_PREFIX = `${MANAGEMENT_API_PATH}/security/back-office/graphics`
+
+/**
+ * Crombolo's own marks, as Umbraco's names them. The plain names are the ones
+ * the client asks for on the header bar, which the theme paints orange, so they
+ * get the cocoa mark; the `-alternative` ones sit on white surfaces and get the
+ * orange one.
+ *
+ * `login-background` fills the illustration panel of the client's own sign-in
+ * screen (`umb-auth-view`), which a session timing out puts in front of an
+ * editor. Our login page has no background of its own — it draws a card rather
+ * than Umbraco's split screen — so this is the only request for it, and leaving
+ * it unanswered left that panel an empty rounded rectangle.
+ */
+const GRAPHICS: Record<string, string> = {
+  logo: 'branding/logo-header.svg',
+  'logo-alternative': 'branding/logo-surface.svg',
+  'login-logo': 'branding/logo-header.svg',
+  'login-logo-alternative': 'branding/logo-surface.svg',
+  'login-background': 'branding/backdrop.svg',
+}
+
+/**
+ * Vendored asset paths served as crombolo's instead.
+ *
+ * These are Umbraco's own marks and artwork, which MIT does not license:
+ * MIT grants copyright permission and says nothing about trademarks. Each is
+ * requested by a vendored element that hard-codes its path, so the substitution
+ * happens here rather than by patching the client, and the originals are no
+ * longer committed under `backoffice-dist/upstream-static/`.
+ *
+ * `resolveStaticFile` consults this before falling back to `vendorDir`, on both
+ * the hashed and the plain prefix, so there is no path left that reaches an
+ * Umbraco mark.
+ *
+ * - `favicon.svg` — the Umbraco "U" roundel, requested by the shells
+ * - `umbraco-logo.svg` — the wordmark, requested by the header popover
+ * - `installer-illustration.svg` — the backdrop of `app-error.element.js`, which
+ *   is a real runtime path, so this needs a replacement rather than a deletion
+ */
+export const BRANDED_ASSETS: Readonly<Record<string, string>> = {
+  'assets/favicon.svg': 'branding/favicon.svg',
+  'assets/umbraco-logo.svg': 'branding/logo-surface.svg',
+  'assets/installer-illustration.svg': 'branding/backdrop.svg',
+}
+
+/**
+ * The same substitution for a file the bundler names after its contents, where
+ * an exact path would be right until the next `vendor:backoffice` and then
+ * quietly wrong.
+ *
+ * `icon-umbraco.js` is the "U" roundel as a registry icon.
+ * `branding/icon-registry.js` keeps that name out of the icon picker, but the
+ * registry is addressed by name and any element may render one, so the glyph
+ * behind the name is ours as well. The bundled app — the one the shells load —
+ * asks for it as `chunks/icon-umbraco-<hash>.js`, while the unbundled tree has
+ * it under `packages/core/icon-registry/icons/`. Both are the one glyph.
+ */
+const BRANDED_PATTERNS: readonly (readonly [RegExp, string])[] = [
+  [/(?:^|\/)icon-umbraco(?:-[0-9a-z]+)?\.js$/, 'branding/icon-mark.js'],
+]
+
+/** The crombolo file to serve in place of a vendored one, by vendor-relative path. */
+export function brandedAsset(relative: string): string | undefined {
+  return (
+    BRANDED_ASSETS[relative] ?? BRANDED_PATTERNS.find(([pattern]) => pattern.test(relative))?.[1]
+  )
+}
+
+export function resolveGraphic(paths: BackOfficePaths, pathname: string): string | undefined {
+  const prefix = `${GRAPHICS_PREFIX}/`
+  if (!pathname.startsWith(prefix)) return undefined
+  const graphic = GRAPHICS[pathname.slice(prefix.length)]
+  if (!graphic) return undefined
+  const file = join(paths.pluginDir, graphic)
+  return existsSync(file) ? file : undefined
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './extensions.ts'
+export * from './graphics.ts'
+export * from './login-assets.ts'
+export * from './manifests.ts'
+export * from './paths.ts'
+export * from './shell.ts'
+export * from './static.ts'

package/src/login-assets.ts

@@ -0,0 +1,18 @@
+/**
+ * The login page's client module.
+ *
+ * It is a plain `.js` asset rather than compiled TypeScript because it imports
+ * bare `@umbraco-cms/backoffice/*` specifiers that only resolve in the browser,
+ * through the import map the page embeds.
+ */
+import { join } from 'node:path'
+
+export const LOGIN_ASSET_DIR = join(import.meta.dir, '../assets')
+
+export function resolveLoginAsset(backOfficePath: string, pathname: string): string | undefined {
+  const prefix = `${backOfficePath}/login/`
+  if (!pathname.startsWith(prefix)) return undefined
+  const name = pathname.slice(prefix.length)
+  // Only the files we ship; no traversal, no directory listing.
+  return name === 'login.js' ? join(LOGIN_ASSET_DIR, 'login.js') : undefined
+}

package/src/manifests.ts

@@ -0,0 +1,154 @@
+/**
+ * Package manifest discovery: the vendored client contributes the core
+ * manifest, the framework contributes its own, and each installed npm
+ * extension contributes one (`extensions.ts`).
+ *
+ * The merged importmap is what the shell embeds; without it the backoffice
+ * cannot resolve a single bare `@umbraco-cms/backoffice/*` specifier.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import type { InstalledExtension } from './extensions.ts'
+import type { BackOfficePaths } from './paths.ts'
+import { PLUGIN_PATH_PLACEHOLDER, VENDORED_ASSETS_PATH } from './paths.ts'
+
+export const MANIFEST_FILE_NAME = 'umbraco-package.json'
+
+/**
+ * The assistant's own manifest, which the server omits when the feature is not
+ * configured — so an unconfigured site serves no drawer and no button.
+ */
+export const ASSISTANT_MANIFEST_ID = 'Crombolo.Assistant'
+
+export interface PackageManifestImportmap {
+  imports: Record<string, string>
+  scopes?: Record<string, Record<string, string>>
+}
+
+export interface PackageManifest {
+  name: string
+  id?: string
+  version?: string
+  allowPublicAccess?: boolean
+  allowTelemetry?: boolean
+  allowCacheBusting?: boolean
+  extensions: unknown[]
+  importmap?: PackageManifestImportmap
+}
+
+/** The wire shape of GET /manifest/manifest. */
+export interface ManifestResponseModel {
+  name: string
+  id?: string | null
+  version?: string | null
+  cacheBuster?: string | null
+  extensions: unknown[]
+}
+
+function readManifest(file: string): PackageManifest | undefined {
+  const content = readFileSync(file, 'utf8')
+  if (content.trim().length === 0) return undefined
+  return JSON.parse(content) as PackageManifest
+}
+
+/** Scans a directory for manifests: one in the root, or one per child directory. */
+export function discoverManifests(dir: string): PackageManifest[] {
+  if (!existsSync(dir)) return []
+  const found: PackageManifest[] = []
+  const rootManifest = join(dir, MANIFEST_FILE_NAME)
+  if (existsSync(rootManifest)) {
+    const manifest = readManifest(rootManifest)
+    if (manifest) found.push(manifest)
+  }
+  for (const entry of readdirSync(dir)) {
+    const child = join(dir, entry)
+    if (!statSync(child).isDirectory()) continue
+    const file = join(child, MANIFEST_FILE_NAME)
+    if (!existsSync(file)) continue
+    const manifest = readManifest(file)
+    if (manifest) found.push(manifest)
+  }
+  return found
+}
+
+export interface ManifestSet {
+  all: PackageManifest[]
+  importmap: PackageManifestImportmap
+}
+
+/**
+ * Collects the core manifest plus the installed extensions, and rewrites the
+ * importmap's virtual directory to the cache-busted assets path — exactly what
+ * Umbraco's HtmlHelperBackOfficeExtensions does with a string replace.
+ *
+ * `omit` drops a framework manifest by id, which is how an optional feature
+ * leaves no trace in the backoffice when it is not configured.
+ */
+export function collectManifests(
+  paths: BackOfficePaths,
+  extensions: readonly InstalledExtension[] = [],
+  options: { omit?: readonly string[] } = {},
+): ManifestSet {
+  const omit = new Set(options.omit ?? [])
+  const all = [...discoverManifests(paths.vendorDir), ...frameworkManifests(paths)].filter(
+    (manifest) => !omit.has(manifest.id ?? ''),
+  )
+  all.push(...extensions.map((extension) => extension.manifest))
+
+  const imports: Record<string, string> = {}
+  const scopes: Record<string, Record<string, string>> = {}
+  for (const manifest of all) {
+    if (!manifest.importmap) continue
+    for (const [specifier, target] of Object.entries(manifest.importmap.imports)) {
+      imports[specifier] = rewriteAssetPath(target, paths)
+    }
+    for (const [scope, scopeImports] of Object.entries(manifest.importmap.scopes ?? {})) {
+      const rewritten: Record<string, string> = {}
+      for (const [specifier, target] of Object.entries(scopeImports)) {
+        rewritten[specifier] = rewriteAssetPath(target, paths)
+      }
+      scopes[rewriteAssetPath(scope, paths)] = rewritten
+    }
+  }
+  const importmap: PackageManifestImportmap = { imports }
+  if (Object.keys(scopes).length > 0) importmap.scopes = scopes
+  return { all, importmap }
+}
+
+/** The framework's own package, its element paths rewritten to wherever the backoffice is mounted. */
+function frameworkManifests(paths: BackOfficePaths): PackageManifest[] {
+  return discoverManifests(paths.pluginDir).map((manifest) => {
+    const text = JSON.stringify(manifest).replaceAll(
+      `"${PLUGIN_PATH_PLACEHOLDER}/`,
+      `"${paths.pluginPath}/`,
+    )
+    return JSON.parse(text) as PackageManifest
+  })
+}
+
+function rewriteAssetPath(target: string, paths: BackOfficePaths): string {
+  return target.startsWith(VENDORED_ASSETS_PATH)
+    ? `${paths.assetsPath}${target.slice(VENDORED_ASSETS_PATH.length)}`
+    : target
+}
+
+/** Public manifests are the ones the login screen may load before sign-in. */
+export function toResponseModels(
+  manifests: readonly PackageManifest[],
+  cacheBuster: string,
+  visibility: 'all' | 'public' | 'private' = 'all',
+): ManifestResponseModel[] {
+  return manifests
+    .filter((m) => {
+      if (visibility === 'all') return true
+      const isPublic = m.allowPublicAccess === true
+      return visibility === 'public' ? isPublic : !isPublic
+    })
+    .map((m) => ({
+      name: m.name,
+      id: m.id ?? null,
+      version: m.version ?? null,
+      cacheBuster: m.allowCacheBusting === false ? null : cacheBuster,
+      extensions: m.extensions ?? [],
+    }))
+}

package/src/paths.ts

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { DEFAULT_BACKOFFICE_PATH as CORE_DEFAULT } from '@crombolo/core'
+
+/**
+ * Path layout for the hosted backoffice.
+ *
+ * Umbraco serves assets from a cache-busted virtual directory,
+ * `/umbraco/backoffice/<hash>/…`, and rewrites the hash away in middleware. We
+ * reproduce that because the import map and the shell both embed the hashed
+ * path, and long-lived immutable caching depends on it.
+ */
+export interface BackOfficePaths {
+  /** e.g. /umbraco */
+  readonly backOfficePath: string
+  /** e.g. /umbraco/backoffice */
+  readonly virtualDirectory: string
+  /** e.g. /umbraco/backoffice/a1b2c3d4 */
+  readonly assetsPath: string
+  readonly cacheBustHash: string
+  /** Directory on disk holding the vendored client. */
+  readonly vendorDir: string
+  /** e.g. /crombolo/crombolo — where the framework's own backoffice package is served. */
+  readonly pluginPath: string
+  /** Directory on disk holding that package: a manifest and its modules. */
+  readonly pluginDir: string
+}
+
+export { DEFAULT_BACKOFFICE_PATH } from '@crombolo/core'
+
+/**
+ * Where the vendored client's own manifest says its assets live. The vendor
+ * script bakes this literal in, so it is the prefix to rewrite from however the
+ * backoffice is mounted — not `virtualDirectory`, which moves with it.
+ */
+export const VENDORED_ASSETS_PATH = '/umbraco/backoffice'
+
+/**
+ * The stand-in our own manifests use for their element paths, which
+ * `collectManifests` rewrites to `pluginPath`. Nothing is ever served from it:
+ * the real path moves with wherever the backoffice is mounted, and a manifest on
+ * disk cannot know that, so it names this instead.
+ */
+export const PLUGIN_PATH_PLACEHOLDER = '/crombolo-plugin'
+
+export interface BackOfficePathOptions {
+  backOfficePath?: string
+  vendorDir?: string
+  pluginDir?: string
+}
+
+/** The framework's backoffice package: the Changes dashboard and the read-only banner. */
+export function defaultPluginDir(): string {
+  return join(import.meta.dir, '../plugin')
+}
+
+/** Derived from the vendored VERSION so a re-vendor invalidates browser caches. */
+export function cacheBustHash(vendorDir: string): string {
+  const versionFile = join(vendorDir, 'VERSION')
+  const seed = existsSync(versionFile) ? readFileSync(versionFile, 'utf8').trim() : 'unvendored'
+  return createHash('sha256').update(seed).digest('hex').slice(0, 16)
+}
+
+/**
+ * The built client ships as its own package, `@crombolo/backoffice-dist`, so it
+ * is resolved like any dependency. The fallback is the monorepo layout, for a
+ * checkout where the workspace has not been installed yet.
+ */
+export function defaultVendorDir(): string {
+  try {
+    return join(
+      dirname(Bun.resolveSync('@crombolo/backoffice-dist/package.json', import.meta.dir)),
+      'dist',
+    )
+  } catch {
+    return join(import.meta.dir, '../../backoffice-dist/dist')
+  }
+}
+
+export function createBackOfficePaths(options: BackOfficePathOptions = {}): BackOfficePaths {
+  const backOfficePath = (options.backOfficePath ?? CORE_DEFAULT).replace(/\/+$/, '')
+  const vendorDir = options.vendorDir ?? defaultVendorDir()
+  const virtualDirectory = `${backOfficePath}/backoffice`
+  const hash = cacheBustHash(vendorDir)
+  return {
+    backOfficePath,
+    virtualDirectory,
+    assetsPath: `${virtualDirectory}/${hash}`,
+    cacheBustHash: hash,
+    vendorDir,
+    pluginPath: `${backOfficePath}/crombolo`,
+    pluginDir: options.pluginDir ?? defaultPluginDir(),
+  }
+}
+
+/**
+ * Client-side routes the SPA owns. Umbraco constrains its catch-all to these,
+ * so anything else under /umbraco is a genuine 404 rather than the shell.
+ */
+export const SPA_ROUTES = [
+  'section',
+  'preview',
+  'upgrade',
+  'install',
+  'oauth_complete',
+  'logout',
+  'error',
+] as const
+
+export function isSpaRoute(backOfficePath: string, pathname: string): boolean {
+  if (pathname === backOfficePath || pathname === `${backOfficePath}/`) return true
+  if (!pathname.startsWith(`${backOfficePath}/`)) return false
+  const rest = pathname.slice(backOfficePath.length + 1)
+  const first = rest.split('/')[0] ?? ''
+  return SPA_ROUTES.includes(first as (typeof SPA_ROUTES)[number])
+}

package/src/shell.ts

@@ -0,0 +1,139 @@
+/**
+ * The server-rendered HTML shells. This is the server's entire HTML
+ * responsibility: everything else is the SPA.
+ *
+ * Ported from Umbraco.Cms.StaticAssets/umbraco/UmbracoBackOffice/Index.cshtml
+ * and .../UmbracoLogin/Index.cshtml.
+ */
+
+import { MANAGEMENT_API_PATH } from '@crombolo/core'
+import type { PackageManifestImportmap } from './manifests.ts'
+import type { BackOfficePaths } from './paths.ts'
+
+export interface ShellSettings {
+  /** GlobalSettings.DefaultUILanguage — the initial UI language. */
+  defaultUiLanguage: string
+  /** SecuritySettings.KeepUserLoggedIn. */
+  keepUserLoggedIn: boolean
+  title: string
+}
+
+export const DEFAULT_SHELL_SETTINGS: ShellSettings = {
+  defaultUiLanguage: 'en-US',
+  keepUserLoggedIn: false,
+  title: 'Crombolo',
+}
+
+export interface LoginShellSettings {
+  usernameIsEmail: boolean
+  allowUserInvite: boolean
+  allowPasswordReset: boolean
+  disableLocalLogin: boolean
+  /**
+   * Where to go once signed in. The authorize endpoint puts its own URL here, so
+   * the browser resumes the OAuth flow rather than landing on a blank editor.
+   */
+  returnUrl?: string
+}
+
+const escapeHtml = (value: string): string =>
+  value.replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string,
+  )
+
+const noscript = (logoUrl: string): string => `<noscript>
+  <style>
+    #noscript-container { display: flex; flex-wrap: wrap; flex-direction: column;
+      align-items: center; justify-content: center; height: 100vh; padding: 0 20px;
+      text-align: center; }
+  </style>
+  <div id="noscript-container">
+    <h1 aria-hidden="true" class="uui-h3" style="display: inline-flex; align-items: center; gap: 10px">
+      <img alt="logo" src="${logoUrl}" style="width: 100%" />
+    </h1>
+    <p>For full functionality of Crombolo it is necessary to enable JavaScript.</p>
+  </div>
+</noscript>`
+
+/** The `<base href>` must end in a slash: the client router derives its base from it. */
+export function renderBackOfficeShell(
+  paths: BackOfficePaths,
+  importmap: PackageManifestImportmap,
+  settings: ShellSettings = DEFAULT_SHELL_SETTINGS,
+): string {
+  const assets = paths.assetsPath
+  const keepLoggedIn = settings.keepUserLoggedIn ? ' keep-user-logged-in' : ''
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <base href="${paths.backOfficePath}/" />
+  <link rel="icon" type="image/svg+xml" href="${assets}/assets/favicon.svg" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="mobile-web-app-capable" content="yes" />
+  <meta name="robots" content="noindex, nofollow" />
+  <meta name="pinterest" content="nopin" />
+  <meta name="application-name" content="${escapeHtml(settings.title)}" />
+  <title>${escapeHtml(settings.title)}</title>
+  <link rel="stylesheet" href="${assets}/css/umb-css.css" />
+  <link rel="stylesheet" href="${assets}/css/light.css" />
+  <link rel="stylesheet" href="${paths.pluginPath}/branding/theme.css" />
+  <script type="importmap">
+${JSON.stringify(importmap, null, 2)}
+  </script>
+  <script type="module" src="${assets}/apps/app/app.element.js"></script>
+</head>
+<body class="uui-font uui-text" style="margin: 0; padding: 0; overflow: hidden">
+${noscript(`${MANAGEMENT_API_PATH}/security/back-office/graphics/login-logo-alternative`)}
+${
+  /* The client defaults this to '/umbraco' and builds its OAuth redirect_uri
+      and post-logout URL from it, so it must be told where the editor is. */ ''
+}
+<umb-app lang="${escapeHtml(settings.defaultUiLanguage)}" backoffice-path="${escapeHtml(paths.backOfficePath)}"${keepLoggedIn}></umb-app>
+</body>
+</html>
+`
+}
+
+export function renderLoginShell(
+  paths: BackOfficePaths,
+  importmap: PackageManifestImportmap,
+  settings: ShellSettings & LoginShellSettings,
+): string {
+  const assets = paths.assetsPath
+  const graphics = `${MANAGEMENT_API_PATH}/security/back-office/graphics`
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <base href="${paths.backOfficePath}/" />
+  <link rel="icon" type="image/svg+xml" href="${assets}/assets/favicon.svg" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="robots" content="noindex, nofollow" />
+  <meta name="application-name" content="${escapeHtml(settings.title)}" />
+  <title>${escapeHtml(settings.title)}</title>
+  <link rel="stylesheet" href="${assets}/css/light.css" />
+  <link rel="stylesheet" href="${paths.pluginPath}/branding/theme.css" />
+  <style>body { margin: 0; padding: 0; background-color: #fff7ea; }</style>
+  <script type="importmap">
+${JSON.stringify(importmap, null, 2)}
+  </script>
+  <script type="module" src="${paths.backOfficePath}/login/login.js"></script>
+</head>
+<body class="uui-font uui-text" style="margin: 0; padding: 0; overflow: hidden">
+${noscript(`${graphics}/login-logo-alternative`)}
+<crombolo-login
+  lang="${escapeHtml(settings.defaultUiLanguage)}"
+  return-url="${escapeHtml(settings.returnUrl ?? paths.backOfficePath)}"
+  logo-image="${graphics}/login-logo"
+  logo-image-alternative="${graphics}/login-logo-alternative"
+  ${settings.usernameIsEmail ? 'username-is-email' : ''}
+  ${settings.allowUserInvite ? 'allow-user-invite' : ''}
+  ${settings.allowPasswordReset ? 'allow-password-reset' : ''}
+  ${settings.disableLocalLogin ? 'disable-local-login' : ''}>
+</crombolo-login>
+</body>
+</html>
+`
+}

package/src/static.ts

@@ -0,0 +1,107 @@
+/**
+ * Static serving for the vendored client.
+ *
+ * Two behaviours are load-bearing: the cache-bust path segment is stripped
+ * before the file is looked up (Umbraco does this with a rewrite rule), and the
+ * hashed prefix gets immutable caching while the unhashed one does not.
+ */
+import { join, normalize } from 'node:path'
+import { type InstalledExtension, resolveExtensionFile } from './extensions.ts'
+import { brandedAsset } from './graphics.ts'
+import type { BackOfficePaths } from './paths.ts'
+import { VENDORED_ASSETS_PATH } from './paths.ts'
+
+const IMMUTABLE = 'public, max-age=31536000, immutable'
+
+export interface StaticOptions {
+  /** The installed npm extensions, which serve their own assets at /packages/. */
+  extensions?: readonly InstalledExtension[]
+  /** Serve the hashed prefix with immutable caching. Off in development. */
+  immutable?: boolean
+}
+
+/** Rejects any path that escapes the root once normalised. */
+function safeJoin(root: string, relative: string): string | undefined {
+  const decoded = decodeURIComponent(relative)
+  if (decoded.includes('\0')) return undefined
+  const target = normalize(join(root, decoded))
+  const rootWithSep = root.endsWith('/') ? root : `${root}/`
+  return target.startsWith(rootWithSep) ? target : undefined
+}
+
+export interface StaticMatch {
+  file: string
+  cacheControl: string
+}
+
+/**
+ * Resolves a request path to a file on disk, or undefined if this request is not
+ * ours. Strips the cache-bust segment, as Umbraco's rewrite does.
+ */
+export function resolveStaticFile(
+  paths: BackOfficePaths,
+  pathname: string,
+  options: StaticOptions = {},
+): StaticMatch | undefined {
+  const hashedPrefix = `${paths.assetsPath}/`
+  if (pathname.startsWith(hashedPrefix)) {
+    const relative = pathname.slice(hashedPrefix.length)
+    const branded = brandedAsset(relative)
+    if (branded) return { file: join(paths.pluginDir, branded), cacheControl: 'no-cache' }
+    const file = safeJoin(paths.vendorDir, relative)
+    if (!file) return undefined
+    return { file, cacheControl: options.immutable === false ? 'no-cache' : IMMUTABLE }
+  }
+
+  // The vendored literal is an alias for wherever the editor is mounted: parts
+  // of the client hard-code `/umbraco/backoffice/…` for an asset — the header
+  // popover's logo, for one — and those requests arrive whatever the path is.
+  const plainPrefix = [`${paths.virtualDirectory}/`, `${VENDORED_ASSETS_PATH}/`].find((prefix) =>
+    pathname.startsWith(prefix),
+  )
+  if (plainPrefix) {
+    // A stale hash from a previous deploy lands here; serve it, but do not cache.
+    const rest = pathname.slice(plainPrefix.length)
+    const withoutStaleHash = /^[0-9a-f]{16}\//.test(rest) ? rest.slice(17) : rest
+    const branded = brandedAsset(withoutStaleHash)
+    if (branded) return { file: join(paths.pluginDir, branded), cacheControl: 'no-cache' }
+    const file = safeJoin(paths.vendorDir, withoutStaleHash)
+    if (!file) return undefined
+    return { file, cacheControl: 'no-cache' }
+  }
+
+  const pluginPrefix = `${paths.pluginPath}/`
+  if (pathname.startsWith(pluginPrefix)) {
+    const file = safeJoin(paths.pluginDir, pathname.slice(pluginPrefix.length))
+    if (!file) return undefined
+    return { file, cacheControl: 'no-cache' }
+  }
+
+  // An installed extension's own files, resolved inside the package it names
+  // and nowhere else. `no-cache` for the same reason the framework plugin uses
+  // it: a version bump moves the file behind an unchanged path.
+  if (options.extensions && options.extensions.length > 0) {
+    const file = resolveExtensionFile(options.extensions, pathname)
+    if (file) return { file, cacheControl: 'no-cache' }
+  }
+
+  return undefined
+}
+
+/** Serves a resolved file, honouring If-None-Match. */
+export async function serveStaticFile(
+  match: StaticMatch,
+  request: Request,
+): Promise<Response | undefined> {
+  const file = Bun.file(match.file)
+  if (!(await file.exists())) return undefined
+
+  const etag = `W/"${file.size.toString(16)}-${Math.floor(file.lastModified).toString(16)}"`
+  const headers = new Headers({ etag, 'cache-control': match.cacheControl })
+  if (file.type) headers.set('content-type', file.type)
+
+  if (request.headers.get('if-none-match') === etag) {
+    return new Response(null, { status: 304, headers })
+  }
+  return new Response(file, { headers })
+}

package/src/text-imports.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `import x from './y.svg' with { type: 'text' }` — the file's contents as a
+ * string, which Bun inlines at bundle time.
+ *
+ * TypeScript has no knowledge of a bundler's loaders, so the shape has to be
+ * declared. Only `.svg` and `.css` are declared, and only `branding.ts` imports
+ * either: a wider declaration would make a mistyped asset import compile.
+ *
+ * `branding.ts` references this file directly, rather than relying on it being
+ * in anyone's `include`. The published package ships `.ts` source, so a
+ * consumer's own `tsc` compiles `branding.ts` — and without the reference it
+ * would compile it against no declaration and fail on an import it cannot
+ * explain, in a file the consumer does not own.
+ */
+declare module '*.svg' {
+  const contents: string
+  export default contents
+}
+
+declare module '*.css' {
+  const contents: string
+  export default contents
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.