@effindomv2/fui-as 0.1.20 → 0.1.22

package/browser/loading-overlay-body.html

@@ -0,0 +1,13 @@
+<div
+  class="effindom-loading-overlay"
+  id="effindom-loading-overlay"
+  data-state="loading"
+  aria-live="polite"
+  aria-hidden="true"
+  hidden>
+  <div class="effindom-loading-card">
+    <p class="effindom-loading-kicker">EffinDom backstage</p>
+    <h2 class="effindom-loading-title" id="effindom-loading-title">Teaching the pixels their lines...</h2>
+    <p class="effindom-loading-detail" id="effindom-loading-detail">The runtime orchestra is tuning up behind the canvas.</p>
+  </div>
+</div>

package/browser/loading-overlay-styles.html

@@ -0,0 +1,52 @@
+.effindom-loading-overlay {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+  box-sizing: border-box;
+  background: linear-gradient(180deg, rgba(2, 6, 23, 0.72), rgba(10, 20, 34, 0.82));
+  backdrop-filter: blur(10px);
+  z-index: 2;
+}
+
+.effindom-loading-overlay[hidden] {
+  display: none;
+}
+
+.effindom-loading-card {
+  max-width: 420px;
+  padding: 22px 24px;
+  border: 1px solid rgba(148, 163, 184, 0.32);
+  border-radius: 18px;
+  background: rgba(6, 12, 21, 0.80);
+  text-align: center;
+  box-shadow: 0 18px 48px rgba(2, 6, 23, 0.30);
+}
+
+.effindom-loading-overlay[data-state="error"] .effindom-loading-card {
+  border-color: rgba(248, 113, 113, 0.50);
+  background: rgba(69, 10, 10, 0.78);
+}
+
+.effindom-loading-kicker {
+  margin: 0 0 10px;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: #7dd3fc;
+}
+
+.effindom-loading-title {
+  margin: 0;
+  font-size: 28px;
+  line-height: 1.15;
+}
+
+.effindom-loading-detail {
+  margin: 12px 0 0;
+  font-size: 14px;
+  line-height: 1.55;
+  color: #cbd5e1;
+}

package/browser/routed-app-conventions.ts

@@ -0,0 +1 @@
+export * from './src/routed-app-conventions';

package/browser/src/common-harness/managed-harness.ts

@@ -71,26 +71,10 @@ const decoder = new TextDecoder();
 const encoder = new TextEncoder();
 const harnessUiChrome = new HarnessUiChrome();
 
-function setLoadingOverlay(state: 'loading' | 'error', title: string, detail: string): void {
-  harnessUiChrome.setLoadingOverlay(state, title, detail);
-}
-
-function hideLoadingOverlay(): void {
-  harnessUiChrome.hideLoadingOverlay();
-}
-
 function describeHarnessError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function reportHarnessErrorOverlay(title: string, detail: string, error: unknown): void {
-  console.error(error instanceof Error ? error.stack ?? error : error);
-  setLoadingOverlay('error', title, detail);
-  const windowWithHarnessError = window as Window & { __fuiAsError?: string; __fuiAsReady?: boolean };
-  windowWithHarnessError.__fuiAsReady = false;
-  windowWithHarnessError.__fuiAsError = detail;
-}
-
 function defaultRunHarnessApp(exports: HarnessExports): void {
   const autoExports = exports as AutoHarnessExports;
   if (typeof autoExports.__runApp !== 'function') {
@@ -118,23 +102,7 @@ function defaultOnReady(): void {
 function defaultOnError(error: unknown): void {
   const windowWithHarnessState = window as Window & { __fuiAsReady?: boolean; __fuiAsError?: string };
   windowWithHarnessState.__fuiAsReady = false;
-  windowWithHarnessState.__fuiAsError = describeHarnessError(error);
-}
-
-function setUrlPreviewText(text: string): void {
-  harnessUiChrome.setUrlPreviewText(text);
-}
-
-function detectPlatformFamily(): number {
-  return harnessUiChrome.detectPlatformFamily();
-}
-
-function detectCoarsePointer(): boolean {
-  return harnessUiChrome.detectCoarsePointer();
-}
-
-function getCanvasSizeSource(canvas: HTMLCanvasElement): HTMLElement | HTMLCanvasElement {
-  return harnessUiChrome.getCanvasSizeSource(canvas);
+  windowWithHarnessState.__fuiAsError = error instanceof Error ? error.message : String(error);
 }
 
 export function startHarness<Exports extends HarnessExports>(options: HarnessOptions<Exports>): void {
@@ -158,16 +126,59 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
   let cleanup = () => {
     delete window.__fui_debug;
   };
-  setLoadingOverlay(
-    'loading',
-    'Teaching the pixels their lines...',
-    'The runtime orchestra is tuning up behind the canvas.',
-  );
+  const loadingOverlayText = harnessUiChrome.getLoadingOverlayText();
+  let loadingOverlayTitle = loadingOverlayText.title;
+  let loadingOverlayDetail = loadingOverlayText.detail;
+  let loadingOverlayVisible = false;
+  let loadingOverlayTimer: number | null = null;
+
+  function clearLoadingOverlayTimer(): void {
+    if (loadingOverlayTimer === null) {
+      return;
+    }
+    window.clearTimeout(loadingOverlayTimer);
+    loadingOverlayTimer = null;
+  }
+
+  function scheduleLoadingOverlay(): void {
+    if (loadingOverlayVisible || loadingOverlayTimer !== null) {
+      return;
+    }
+    loadingOverlayTimer = window.setTimeout(() => {
+      loadingOverlayTimer = null;
+      loadingOverlayVisible = true;
+      harnessUiChrome.setLoadingOverlay('loading', loadingOverlayTitle, loadingOverlayDetail);
+    }, 1000);
+  }
+
+  function updateLoadingOverlay(detail: string): void {
+    loadingOverlayDetail = detail;
+    if (loadingOverlayVisible) {
+      harnessUiChrome.setLoadingOverlay('loading', loadingOverlayTitle, loadingOverlayDetail);
+      return;
+    }
+    scheduleLoadingOverlay();
+  }
+
+  function finishLoadingOverlay(): void {
+    clearLoadingOverlayTimer();
+    loadingOverlayVisible = false;
+    harnessUiChrome.hideLoadingOverlay();
+  }
+
+  function failLoadingOverlay(detail: string): void {
+    clearLoadingOverlayTimer();
+    loadingOverlayVisible = true;
+    harnessUiChrome.setLoadingOverlay('error', loadingOverlayTitle, detail);
+  }
+
   const bridge = window.EffinDomBrowserBridge;
   if (bridge === undefined) {
+    failLoadingOverlay('EffinDomBrowserBridge is unavailable.');
     throw new Error('EffinDomBrowserBridge is unavailable.');
   }
   if (typeof Worker !== 'function') {
+    failLoadingOverlay('FUI-AS requires browser Worker support.');
     throw new Error('FUI-AS requires browser Worker support.');
   }
   const bridgeState = bridge;
@@ -195,7 +206,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
       offsets: number[];
       colors: number[];
     }>();
-    setUrlPreviewText('');
+    harnessUiChrome.setUrlPreviewText('');
 
     function getCurrentSession(): HarnessAppSession {
       if (currentSession === null) {
@@ -761,8 +772,12 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
 
     function handleSameOriginNavigationFailure(target: URL, mode: HarnessNavigationMode, error: unknown): void {
       const route = toAppRoute(target);
-      const detail = `Failed to load ${mode === 'pop' ? 'history route' : 'route'} ${route}: ${describeHarnessError(error)}`;
-      reportHarnessErrorOverlay('The render raccoons chewed through a cable.', detail, error);
+      const detail = `Failed to load ${mode === 'pop' ? 'history route' : 'route'} ${route}: ${error instanceof Error ? error.message : String(error)}`;
+      console.error(error instanceof Error ? error.stack ?? error : error);
+      failLoadingOverlay(detail);
+      const windowWithHarnessError = window as Window & { __fuiAsError?: string; __fuiAsReady?: boolean };
+      windowWithHarnessError.__fuiAsReady = false;
+      windowWithHarnessError.__fuiAsError = detail;
       options.onError?.(error);
     }
 
@@ -1041,7 +1056,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
         session.exports.__fui_hide_active_context_menu();
       }
       runtime.clearPointerHover();
-      setUrlPreviewText('');
+      harnessUiChrome.setUrlPreviewText('');
     };
     const handleWindowBlur = () => {
       dismissTransientUi();
@@ -1120,7 +1135,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
     };
     registerExternalDragTarget(runtime.canvas);
     registerExternalDragTarget(runtime.canvas.parentElement);
-    registerExternalDragTarget(getCanvasSizeSource(runtime.canvas));
+    registerExternalDragTarget(harnessUiChrome.getCanvasSizeSource(runtime.canvas));
     window.addEventListener('blur', handleWindowBlur);
     runtime.canvas.addEventListener('blur', handleCanvasBlur);
     for (let index = 0; index < externalDragTargets.length; index += 1) {
@@ -1135,7 +1150,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
 
     cleanup = () => {
       workerManager.terminateAll();
-      setUrlPreviewText('');
+      harnessUiChrome.setUrlPreviewText('');
       window.removeEventListener('resize', handleViewportChange);
       darkModeQuery.removeEventListener('change', handleDarkModeChange);
       window.removeEventListener('popstate', handlePopState);
@@ -1285,7 +1300,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
       runtime.setCapturedPointerHandle(null);
       runtime.clearPointerHover();
       runtime.canvas.style.cursor = 'default';
-      setUrlPreviewText('');
+      harnessUiChrome.setUrlPreviewText('');
       runtime.core._ed_clear_focus_state?.();
       runtime.core._ed_clear_text_input_state?.();
       runtime.core._ed_reset_scene();
@@ -1315,7 +1330,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
       runtime.setAppFrameHandler(null);
       runtime.setCapturedPointerHandle(null);
       runtime.clearPointerHover();
-      setUrlPreviewText('');
+      harnessUiChrome.setUrlPreviewText('');
       latestCommandWords = [];
       latestRootHandle = null;
       updateState();
@@ -1330,11 +1345,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
       loadOptions: HarnessAppOptions<Exports>,
     ): Promise<HarnessContext<Exports>> {
       if (loadOptions.showLoadingOverlay !== false) {
-        setLoadingOverlay(
-          'loading',
-          'Winding up the tiny widget clockwork...',
-          `Loading ${loadOptions.wasmPath}`,
-        );
+        updateLoadingOverlay(`Loading ${loadOptions.wasmPath}`);
       }
       await unloadApp();
       const restoredSnapshot = await queuePersistedUiStateWork(() => {
@@ -1404,7 +1415,7 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
       await queuePersistedUiStateWork(() => ensureCurrentHistoryEntrySnapshot(`loading ${loadOptions.wasmPath}`));
       lastHandledUrlHref = window.location.href;
       updateState();
-      hideLoadingOverlay();
+      finishLoadingOverlay();
       return context;
     }
 
@@ -1424,12 +1435,12 @@ export function startManagedHarness(options: ManagedHarnessOptions): void {
     await options.onReady?.(controller);
   }).catch((error: unknown) => {
     cleanup();
-    const message = describeHarnessError(error);
-    reportHarnessErrorOverlay(
-      'The render raccoons chewed through a cable.',
-      message,
-      error,
-    );
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(error instanceof Error ? error.stack ?? error : error);
+    failLoadingOverlay(message);
+    const windowWithHarnessError = window as Window & { __fuiAsError?: string; __fuiAsReady?: boolean };
+    windowWithHarnessError.__fuiAsReady = false;
+    windowWithHarnessError.__fuiAsError = message;
     options.onError?.(error);
     throw error;
   });

package/browser/src/common-harness/ui-chrome.ts

@@ -94,6 +94,21 @@ export function waitForFrame(): Promise<void> {
 }
 
 export class HarnessUiChrome {
+  getLoadingOverlayText(): { title: string; detail: string } {
+    const overlay = document.getElementById(LOADING_OVERLAY_ID);
+    const titleNode = document.getElementById(LOADING_TITLE_ID);
+    const detailNode = document.getElementById(LOADING_DETAIL_ID);
+    const title = titleNode instanceof HTMLElement ? titleNode.textContent ?? '' : '';
+    const detail = detailNode instanceof HTMLElement ? detailNode.textContent ?? '' : '';
+    if (overlay instanceof HTMLElement && title.length > 0 && detail.length > 0) {
+      return { title, detail };
+    }
+    return {
+      title: 'Loading...',
+      detail: 'The runtime is starting up.',
+    };
+  }
+
   setLoadingOverlay(state: 'loading' | 'error', title: string, detail: string): void {
     const overlay = document.getElementById(LOADING_OVERLAY_ID);
     const titleNode = document.getElementById(LOADING_TITLE_ID);

package/browser/src/index.ts

@@ -23,16 +23,39 @@ export type {
   ManagedHistoryState,
 } from './common-harness';
 
+export {
+  buildRoutedHarnessRoutes,
+  defineRoutedAppManifest,
+  renderRoutedPageHead,
+  resolveRouteManifest,
+  resolveRoutePath,
+  routeDef,
+  routeHead,
+} from './routed-app-conventions';
+
 export {
   startRoutedHarness,
 } from './routed-harness';
 
+export type {
+  RoutedAppHeadTag,
+  RoutedAppRoute,
+  RoutedAppRouteDefinition,
+  RoutedAppRouteManifest,
+  ResolvedRoutedAppRoute,
+  ResolvedRoutedAppRouteManifest,
+} from './routed-app-conventions';
+
 export type {
   RoutedHarnessConfig,
   RoutedHarnessManagerState,
   RoutedHarnessRoute,
 } from './routed-harness';
 
+export type {
+  RoutedHarnessRouteSpec,
+} from './routed-app-conventions';
+
 export {
   defineHostEvents,
   hostEvent,

package/browser/src/routed-app-conventions.ts

@@ -0,0 +1,292 @@
+export class RoutedAppHeadTag {
+  kind: string;
+  name: string;
+  content: string;
+
+  constructor(kind: string = "", name: string = "", content: string = "") {
+    this.kind = kind;
+    this.name = name;
+    this.content = content;
+  }
+}
+
+export class RoutedAppRoute {
+  key: string;
+  title: string;
+  headTags: Array<RoutedAppHeadTag>;
+  entrypoint: string;
+  wasmFile: string;
+  shellDir: string;
+  sourceRoutePath: string;
+  publishedRoutePath: string;
+
+  constructor(
+    key: string = "",
+    title: string = "",
+    headTags: Array<RoutedAppHeadTag> = new Array<RoutedAppHeadTag>(),
+    entrypoint: string = "",
+    wasmFile: string = "",
+    shellDir: string = "",
+    sourceRoutePath: string = "",
+    publishedRoutePath: string = "",
+  ) {
+    this.key = key;
+    this.title = title;
+    this.headTags = headTags;
+    this.entrypoint = entrypoint;
+    this.wasmFile = wasmFile;
+    this.shellDir = shellDir;
+    this.sourceRoutePath = sourceRoutePath;
+    this.publishedRoutePath = publishedRoutePath;
+  }
+}
+
+export class RoutedAppRouteManifest {
+  sourceRouteBase: string;
+  routes: Array<RoutedAppRoute>;
+
+  constructor(sourceRouteBase: string = "", routes: Array<RoutedAppRoute> = new Array<RoutedAppRoute>()) {
+    this.sourceRouteBase = sourceRouteBase;
+    this.routes = routes;
+  }
+}
+
+export class ResolvedRoutedAppRoute {
+  key: string;
+  title: string;
+  headTags: Array<RoutedAppHeadTag>;
+  shellDir: string;
+  wasmFile: string;
+  entrypoint: string;
+  sourceRoutePath: string;
+  publishedRoutePath: string;
+
+  constructor(
+    key: string = "",
+    title: string = "",
+    headTags: Array<RoutedAppHeadTag> = new Array<RoutedAppHeadTag>(),
+    shellDir: string = "",
+    wasmFile: string = "",
+    entrypoint: string = "",
+    sourceRoutePath: string = "",
+    publishedRoutePath: string = "",
+  ) {
+    this.key = key;
+    this.title = title;
+    this.headTags = headTags;
+    this.shellDir = shellDir;
+    this.wasmFile = wasmFile;
+    this.entrypoint = entrypoint;
+    this.sourceRoutePath = sourceRoutePath;
+    this.publishedRoutePath = publishedRoutePath;
+  }
+}
+
+export class ResolvedRoutedAppRouteManifest {
+  sourceRouteBase: string;
+  routes: Array<ResolvedRoutedAppRoute>;
+
+  constructor(sourceRouteBase: string = "", routes: Array<ResolvedRoutedAppRoute> = new Array<ResolvedRoutedAppRoute>()) {
+    this.sourceRouteBase = sourceRouteBase;
+    this.routes = routes;
+  }
+}
+
+export class RoutedHarnessRouteSpec {
+  routePath: string;
+  wasmPath: string;
+  title: string;
+
+  constructor(routePath: string = "", wasmPath: string = "", title: string = "") {
+    this.routePath = routePath;
+    this.wasmPath = wasmPath;
+    this.title = title;
+  }
+}
+
+export class RoutedAppRouteDefinition {
+  key: string;
+  title: string;
+  entrypoint: string;
+  wasmFile: string;
+  shellDir: string;
+  sourceRoutePath: string;
+  publishedRoutePath: string;
+
+  constructor(
+    key: string = "",
+    title: string = "",
+    entrypoint: string = "",
+    wasmFile: string = "",
+    shellDir: string = "",
+    sourceRoutePath: string = "",
+    publishedRoutePath: string = "",
+  ) {
+    this.key = key;
+    this.title = title;
+    this.entrypoint = entrypoint;
+    this.wasmFile = wasmFile;
+    this.shellDir = shellDir;
+    this.sourceRoutePath = sourceRoutePath;
+    this.publishedRoutePath = publishedRoutePath;
+  }
+}
+
+function trimSlashes(path: string): string {
+  let normalized = path;
+  while (normalized.startsWith("/")) {
+    normalized = normalized.slice(1);
+  }
+  while (normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+function normalizeRouteBase(path: string): string {
+  const trimmed = trimSlashes(path);
+  return trimmed.length === 0 ? "" : `/${trimmed}`;
+}
+
+function toPascalCase(value: string): string {
+  let result = "";
+  let capitalizeNext = true;
+  const normalized = trimSlashes(value);
+  for (let index = 0; index < normalized.length; index += 1) {
+    const char = normalized.charAt(index);
+    const code = char.charCodeAt(0);
+    const isAlphaNum =
+      (code >= 48 && code <= 57) ||
+      (code >= 65 && code <= 90) ||
+      (code >= 97 && code <= 122);
+    if (!isAlphaNum) {
+      capitalizeNext = true;
+      continue;
+    }
+    result += capitalizeNext ? char.toUpperCase() : char;
+    capitalizeNext = false;
+  }
+  return result;
+}
+
+export function routeDef(
+  key: string,
+  title: string,
+  headTags: Array<RoutedAppHeadTag> = new Array<RoutedAppHeadTag>(),
+  entrypoint: string = "",
+  wasmFile: string = "",
+  shellDir: string = "",
+  sourceRoutePath: string = "",
+  publishedRoutePath: string = "",
+): RoutedAppRoute {
+  return new RoutedAppRoute(key, title, headTags, entrypoint, wasmFile, shellDir, sourceRoutePath, publishedRoutePath);
+}
+
+export function defineRoutedAppManifest(
+  sourceRouteBase: string,
+  routes: Array<RoutedAppRoute>,
+): RoutedAppRouteManifest {
+  const normalizedBase = normalizeRouteBase(sourceRouteBase);
+  const normalizedRoutes = new Array<RoutedAppRoute>();
+  for (let index = 0; index < routes.length; index += 1) {
+    const route = routes[index];
+    const routeKey = trimSlashes(route.key);
+    const entrypoint = route.entrypoint == null || route.entrypoint.length == 0 ? `src/routes/${toPascalCase(routeKey)}App.ts` : route.entrypoint;
+    const wasmFile = route.wasmFile == null || route.wasmFile.length == 0 ? `${routeKey}.wasm` : route.wasmFile;
+    const shellDir = route.shellDir == null || route.shellDir.length == 0 ? routeKey : route.shellDir;
+    const sourceRoutePath = route.sourceRoutePath == null || route.sourceRoutePath.length == 0 ? `${normalizedBase}/${routeKey}/` : route.sourceRoutePath;
+    const publishedRoutePath = route.publishedRoutePath == null || route.publishedRoutePath.length == 0 ? `/${routeKey}/` : route.publishedRoutePath;
+    normalizedRoutes.push(new RoutedAppRoute(routeKey, route.title, route.headTags, entrypoint, wasmFile, shellDir, sourceRoutePath, publishedRoutePath));
+  }
+  return new RoutedAppRouteManifest(normalizedBase, normalizedRoutes);
+}
+
+export function resolveRouteManifest(manifest: RoutedAppRouteManifest): ResolvedRoutedAppRouteManifest {
+  const routes = new Array<ResolvedRoutedAppRoute>();
+  for (let index = 0; index < manifest.routes.length; index += 1) {
+    const route = manifest.routes[index];
+    const routeKey = trimSlashes(route.key);
+    routes.push(
+      new ResolvedRoutedAppRoute(
+        routeKey,
+        route.title,
+        route.headTags,
+        routeKey.length == 0 ? "" : routeKey,
+        `${routeKey}.wasm`,
+        `src/routes/${toPascalCase(routeKey)}App.ts`,
+        `${manifest.sourceRouteBase}/${routeKey}/`,
+        `/${routeKey}/`,
+      ),
+    );
+  }
+  return new ResolvedRoutedAppRouteManifest(manifest.sourceRouteBase, routes);
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function pushHeadTag(tags: Array<string>, headTag: RoutedAppHeadTag): void {
+  if (headTag.content.length == 0 || headTag.name.length == 0) {
+    return;
+  }
+  const attribute = headTag.kind == "property" ? "property" : "name";
+  tags.push(`    <meta ${attribute}="${escapeHtml(headTag.name)}" content="${escapeHtml(headTag.content)}" />`);
+}
+
+export function routeHead(...entries: Array<string>): Array<RoutedAppHeadTag> {
+  const headTags = new Array<RoutedAppHeadTag>();
+  for (let index = 0; index + 1 < entries.length; index += 2) {
+    const name = entries[index];
+    const content = entries[index + 1];
+    const kind = name.startsWith("og:") || name.startsWith("fb:") ? "property" : "name";
+    headTags.push(new RoutedAppHeadTag(kind, name, content));
+  }
+  return headTags;
+}
+
+export function renderRoutedPageHead(title: string, headTags: Array<RoutedAppHeadTag> = new Array<RoutedAppHeadTag>()): string {
+  const tags = new Array<string>();
+  const effectiveTitle = title.length == 0 ? "FUI-AS" : title;
+  tags.push(`    <title>${escapeHtml(effectiveTitle)}</title>`);
+  for (let index = 0; index < headTags.length; index += 1) {
+    pushHeadTag(tags, headTags[index]);
+  }
+  return tags.join("\n");
+}
+
+export function buildRoutedHarnessRoutes(
+  manifest: RoutedAppRouteManifest,
+  pathname: string,
+): Array<RoutedHarnessRouteSpec> {
+  const resolvedManifest = resolveRouteManifest(manifest);
+  const routePrefix = pathname.startsWith(`${resolvedManifest.sourceRouteBase}/`) ? resolvedManifest.sourceRouteBase : "";
+  const routes = new Array<RoutedHarnessRouteSpec>();
+  for (let index = 0; index < resolvedManifest.routes.length; index += 1) {
+    const route = resolvedManifest.routes[index];
+    routes.push(
+      new RoutedHarnessRouteSpec(
+        `${routePrefix}${route.publishedRoutePath}`,
+        `${routePrefix}/${route.wasmFile}`.replace("//", "/"),
+        route.title,
+      ),
+    );
+  }
+  return routes;
+}
+
+export function resolveRoutePath(manifest: RoutedAppRouteManifest, routeKey: string, currentRoutePath: string): string {
+  const resolvedManifest = resolveRouteManifest(manifest);
+  const isSourceRoute = currentRoutePath.length == 0 || currentRoutePath.startsWith(`${resolvedManifest.sourceRouteBase}/`);
+  for (let index = 0; index < resolvedManifest.routes.length; index += 1) {
+    const route = resolvedManifest.routes[index];
+    if (route.key == routeKey) {
+      return isSourceRoute ? route.sourceRoutePath : route.publishedRoutePath;
+    }
+  }
+  return "";
+}

package/browser/src/routed-harness.ts

@@ -10,6 +10,7 @@ import {
 import type { HostEventsDefinition } from './host-events';
 import type { HostServicesDefinition } from './host-services';
 import type { WorkerHostServicesBundleConfig } from './worker-types';
+import type { RoutedHarnessRouteSpec } from './routed-app-conventions';
 
 type NavigationMode = 'push' | 'replace' | 'pop';
 
@@ -20,12 +21,9 @@ declare global {
   }
 }
 
-export interface RoutedHarnessRoute {
-  readonly routePath: string;
+export type RoutedHarnessRoute = RoutedHarnessRouteSpec & {
   readonly matchPath?: string;
-  readonly wasmPath: string;
-  readonly title: string;
-}
+};
 
 export interface RoutedHarnessManagerState {
   readonly shellId: string;
@@ -169,9 +167,7 @@ export function startRoutedHarness<
       },
     };
     const showLoadingOverlay = config.showLoadingOverlay?.(isWarmRouteSwap, route);
-    if (showLoadingOverlay !== undefined) {
-      appOptions.showLoadingOverlay = showLoadingOverlay;
-    }
+    appOptions.showLoadingOverlay = showLoadingOverlay ?? !isWarmRouteSwap;
 
     await controller.loadApp(appOptions);
     routeLoads[route.routePath] = (routeLoads[route.routePath] ?? 0) + 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effindomv2/fui-as",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "private": false,
   "license": "AGPL-3.0-only OR LicenseRef-EffinDom-Commercial",
   "description": "EffinDom v2 AssemblyScript frontend framework SDK and browser harness",
@@ -37,6 +37,10 @@
       "types": "./browser/src/index.ts",
       "default": "./browser/src/index.ts"
     },
+    "./browser/routed-app-conventions": {
+      "types": "./browser/routed-app-conventions.ts",
+      "default": "./browser/routed-app-conventions.ts"
+    },
     "./browser/common-harness": {
       "types": "./browser/src/common-harness.ts",
       "default": "./browser/src/common-harness.ts"
@@ -60,6 +64,9 @@
   },
   "files": [
     "src",
+    "browser/routed-app-conventions.ts",
+    "browser/loading-overlay-styles.html",
+    "browser/loading-overlay-body.html",
     "browser/src",
     "scripts",
     "LICENSE.md",
@@ -78,7 +85,7 @@
   },
   "dependencies": {
     "@assemblyscript/loader": "^0.28.17",
-    "@effindomv2/runtime": "0.1.7"
+    "@effindomv2/runtime": "0.1.8"
   },
   "devDependencies": {
     "@as-pect/assembly": "8.1.0",

package/scripts/build.sh

@@ -20,6 +20,8 @@ HOST_SERVICE_GENERATOR_BUILD="${PACKAGE_DIR}/build/generate-host-services.mjs"
 HOST_EVENT_GENERATOR_BUILD="${PACKAGE_DIR}/build/generate-host-events.mjs"
 RUNTIME_CONFIG_FILE="effindom-runtime-config.js"
 DEFAULT_MANIFEST_PATH="./runtime/dist/effindom.v2.manifest.json"
+LOADING_OVERLAY_STYLES_FILE="${PACKAGE_DIR}/browser/loading-overlay-styles.html"
+LOADING_OVERLAY_BODY_FILE="${PACKAGE_DIR}/browser/loading-overlay-body.html"
 
 rm -rf "${OUT_DIR}"
 mkdir -p "${PACKAGE_DIR}/build" "${OUT_DIR}" "${DEMO_OUT_DIR}" "${WORKER_BUILD_DIR}"
@@ -161,6 +163,28 @@ window.__effindomRuntime = Object.assign({}, window.__effindomRuntime, {
 EOF
 }
 
+render_html_with_loading_overlay() {
+  local source="$1"
+  local destination="$2"
+
+  SOURCE_HTML_PATH="${source}" \
+  DEST_HTML_PATH="${destination}" \
+  LOADING_OVERLAY_STYLES_PATH="${LOADING_OVERLAY_STYLES_FILE}" \
+  LOADING_OVERLAY_BODY_PATH="${LOADING_OVERLAY_BODY_FILE}" \
+    node --input-type=module <<'NODE'
+import { readFileSync, writeFileSync } from 'node:fs';
+const source = readFileSync(process.env.SOURCE_HTML_PATH, 'utf8');
+const styles = readFileSync(process.env.LOADING_OVERLAY_STYLES_PATH, 'utf8');
+const body = readFileSync(process.env.LOADING_OVERLAY_BODY_PATH, 'utf8');
+writeFileSync(
+  process.env.DEST_HTML_PATH,
+  source
+    .replace('{{LOADING_OVERLAY_STYLES}}', styles)
+    .replace('{{LOADING_OVERLAY_BODY}}', body),
+);
+NODE
+}
+
 copy_runtime_assets() {
   local destination="$1"
   cp "${RUNTIME_DIST_DIR}/bridge.js" "${destination}/bridge.js"
@@ -312,14 +336,14 @@ npx esbuild "${PACKAGE_DIR}/demo/worker-host-services.ts" \
   --outfile="${WORKER_HOST_SERVICES_BUILD}" \
   --sourcemap
 
-cp "${SMOKE_FIXTURE_DIR}/index.html" "${OUT_DIR}/index.html"
-cp "${PACKAGE_DIR}/demo/index.html" "${DEMO_OUT_DIR}/index.html"
+render_html_with_loading_overlay "${SMOKE_FIXTURE_DIR}/index.html" "${OUT_DIR}/index.html"
+render_html_with_loading_overlay "${PACKAGE_DIR}/demo/index.html" "${DEMO_OUT_DIR}/index.html"
 cp "${PACKAGE_DIR}/demo/demo-texture.png" "${DEMO_OUT_DIR}/demo-texture.png"
 cp "${PACKAGE_DIR}/demo/demo-secondary-texture.png" "${DEMO_OUT_DIR}/demo-secondary-texture.png"
 
 mkdir -p "${DEMO_OUT_DIR}/advanced-controls" "${DEMO_OUT_DIR}/templated-controls"
-cp "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/advanced-controls/index.html"
-cp "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/templated-controls/index.html"
+render_html_with_loading_overlay "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/advanced-controls/index.html"
+render_html_with_loading_overlay "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/templated-controls/index.html"
 
 copy_runtime_assets "${OUT_DIR}"
 copy_runtime_assets "${DEMO_OUT_DIR}"