@wippy-fe/router 0.0.22

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@wippy-fe/router",
+  "version": "0.0.22",
+  "description": "Drop-in Vue Router helpers for Wippy subapps — RouterLink with host-nav detection, canonical memory-router factory, and link classifier re-export.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src/",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "vue-router": "^4.5.0",
+    "@wippy-fe/proxy": "0.0.22"
+  }
+}

package/src/classify.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-export of the link classifier from @wippy-fe/proxy for one-import
+ * convenience in Vue subapps. Canonical home for the classifier is
+ * @wippy-fe/proxy — vanilla JS subapps should import directly from there.
+ */
+export { classifyLink, setLocalRouter } from '@wippy-fe/proxy'
+export type {
+  ClassifierContext,
+  LinkClassification,
+  LinkKind,
+} from '@wippy-fe/proxy'

package/src/create-app-router.ts

@@ -0,0 +1,93 @@
+import type { Router, RouteRecordRaw } from 'vue-router'
+import { host as defaultHost, on as defaultOn, setLocalRouter } from '@wippy-fe/proxy'
+import { createMemoryHistory, createRouter } from 'vue-router'
+
+export interface CreateAppRouterOptions {
+  /**
+   * Initial route path to prime history with. Usually `config.context?.route`
+   * or the subapp's current location from its mount context.
+   */
+  initialPath?: string
+  /**
+   * Override the host API (testing / dev harness). Defaults to the `host`
+   * export from `@wippy-fe/proxy`.
+   */
+  host?: typeof defaultHost
+  /**
+   * Override the event subscription API. Set to `null` to disable the
+   * `@history` subscription entirely. Defaults to `on` from `@wippy-fe/proxy`.
+   */
+  on?: typeof defaultOn | null
+}
+
+/**
+ * Canonical memory-router factory for Wippy subapps.
+ *
+ * Every subapp currently duplicates the same boilerplate:
+ *   - create a memory history
+ *   - prime it with an initial path from context
+ *   - call `host.onRouteChanged` in `afterEach`
+ *   - listen for `@history` events from the host and mirror them to the router
+ *
+ * This factory encapsulates that boilerplate so subapps become one-liners:
+ *
+ *   ```ts
+ *   import { createAppRouter } from '@wippy-fe/router'
+ *   import { routes } from './routes'
+ *
+ *   const router = createAppRouter(routes, {
+ *     initialPath: appConfig.context?.route,
+ *   })
+ *   app.use(router)
+ *   ```
+ *
+ * Memory history is hardcoded — srcdoc iframes do not support `createWebHistory`
+ * (confirmed dead end — `window.location` is non-configurable in srcdoc, and
+ * framework routers read `location.pathname` directly). Only memory-based
+ * routing works inside child iframes.
+ */
+export function createAppRouter(
+  routes: RouteRecordRaw[],
+  options: CreateAppRouterOptions = {},
+): Router {
+  const host = options.host ?? defaultHost
+  const on = options.on === undefined ? defaultOn : options.on
+
+  const history = createMemoryHistory()
+  if (options.initialPath)
+    history.replace(options.initialPath)
+
+  const router = createRouter({ history, routes })
+
+  // Register this router with the link classifier so it can check own
+  // routes before falling back to mount route / system route matching.
+  setLocalRouter((path: string) => router.resolve(path))
+
+  // Track the last navId applied from a parent-initiated update.
+  // When the router navigates in response to a parent @history event,
+  // suppress the resulting afterEach from sending CmdRouteChanged back up
+  // (which would create an echo loop).
+  let lastAppliedNavId: number | undefined
+
+  router.afterEach((to) => {
+    // If this navigation was triggered by a parent @history update,
+    // pass the navId so the host can identify it as an echo and suppress.
+    const navId = lastAppliedNavId
+    lastAppliedNavId = undefined
+    host.onRouteChanged(to.fullPath, navId)
+  })
+
+  if (on) {
+    on('@history', ({ path, navId }: { path?: string, navId?: number }) => {
+      if (!path)
+        return
+      if (navId !== undefined)
+        lastAppliedNavId = navId
+      const normalized = path.startsWith('/') ? path : `/${path}`
+      if (router.currentRoute.value.fullPath !== normalized)
+        router.push(normalized)
+    })
+  }
+
+  return router
+}

package/src/host-router-link.ts

@@ -0,0 +1,45 @@
+import type { PropType } from 'vue'
+import { host } from '@wippy-fe/proxy'
+import { defineComponent, h } from 'vue'
+
+/**
+ * Explicit host-level navigation link. Use when you want to navigate
+ * to a known host page regardless of the current nesting level.
+ *
+ * Unlike `AutoRouterLink` (which classifies links automatically),
+ * `HostRouterLink` ALWAYS sends navigation to the host via postMessage.
+ *
+ * Use cases:
+ *   - Inside a nav-owner child linking to a different host page
+ *   - Anywhere you explicitly want host-level navigation
+ *
+ * Renders a real `<a>` for accessibility / right-click / SEO.
+ * Left-click calls `host.navigate()`. Modifier keys (ctrl, meta, shift)
+ * fall through to the browser default (open in new tab).
+ */
+export const HostRouterLink = defineComponent({
+  name: 'WippyHostRouterLink',
+  props: {
+    to: {
+      type: String as PropType<string>,
+      required: true,
+    },
+  },
+  setup(props, { slots }) {
+    return () => h(
+      'a',
+      {
+        href: props.to,
+        onClick: (e: MouseEvent) => {
+          if (e.defaultPrevented || e.button !== 0)
+            return
+          if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey)
+            return
+          e.preventDefault()
+          host.navigate(props.to)
+        },
+      },
+      slots.default?.(),
+    )
+  },
+})

package/src/index.ts

@@ -0,0 +1,13 @@
+export { classifyLink, setLocalRouter } from './classify'
+export type { ClassifierContext, LinkClassification, LinkKind } from './classify'
+export { createAppRouter, type CreateAppRouterOptions } from './create-app-router'
+export { HostRouterLink } from './host-router-link'
+export { AutoRouterLink, RouterLink } from './router-link'
+export {
+  assertValidMountRoutes,
+  MOUNT_ROUTE_V1_REGEX,
+  type MountRouteIssue,
+  type MountRouteIssueKind,
+  MountRouteValidationError,
+  validateMountRoutes,
+} from './validate-mount-routes'

package/src/router-link.ts

@@ -0,0 +1,132 @@
+import type { PropType } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
+import { host } from '@wippy-fe/proxy'
+import { defineComponent, h } from 'vue'
+import { useRouter, RouterLink as VueRouterLink } from 'vue-router'
+
+/**
+ * Drop-in replacement for Vue Router's `<RouterLink>` that classifies the
+ * target href and dispatches intelligently:
+ *
+ *   - `host-nav`   → preventDefault + `host.navigate(href)` via postMessage
+ *   - `child-nav`  → delegate to the real `<RouterLink>` (normal in-app nav)
+ *   - `external`   → render an `<a>` with `target="_blank" rel="noopener"`
+ *   - `ignore`     → render an `<a>` with a click-preventing handler
+ *
+ * Subapps migrate by changing a single import:
+ *
+ *   ```ts
+ *   // before
+ *   import { RouterLink } from 'vue-router'
+ *
+ *   // after
+ *   import { RouterLink } from '@wippy-fe/router'
+ *   ```
+ *
+ * Props are a compatible subset of vue-router's RouterLink. Slot API
+ * mirrors the default (non-custom) slot of the real RouterLink.
+ */
+export const AutoRouterLink = defineComponent({
+  name: 'WippyAutoRouterLink',
+  props: {
+    to: {
+      type: [String, Object] as PropType<RouteLocationRaw>,
+      required: true,
+    },
+    replace: {
+      type: Boolean,
+      default: false,
+    },
+    activeClass: {
+      type: String,
+      default: undefined,
+    },
+    exactActiveClass: {
+      type: String,
+      default: undefined,
+    },
+    ariaCurrentValue: {
+      type: String as PropType<'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'>,
+      default: 'page',
+    },
+    /**
+     * For `external` kind: sets the anchor's target attribute.
+     * Defaults to `_blank` with safe `rel`. Pass empty string for same-tab.
+     */
+    externalTarget: {
+      type: String,
+      default: '_blank',
+    },
+  },
+  setup(props, { slots }) {
+    const router = useRouter()
+
+    return () => {
+      const resolved = router.resolve(props.to)
+      const classification = host.classifyLink(resolved.href)
+
+      if (classification.kind === 'host-nav') {
+        return h(
+          'a',
+          {
+            'href': resolved.href,
+            'onClick': (event: MouseEvent) => {
+              if (event.defaultPrevented)
+                return
+              if (event.button !== 0)
+                return
+              if (event.metaKey || event.altKey || event.ctrlKey || event.shiftKey)
+                return
+              event.preventDefault()
+              host.navigate(classification.normalizedPath ?? classification.href)
+            },
+            'aria-current': props.ariaCurrentValue,
+          },
+          slots.default?.(),
+        )
+      }
+
+      if (classification.kind === 'external') {
+        const isBlank = props.externalTarget === '_blank'
+        return h(
+          'a',
+          {
+            href: resolved.href,
+            target: props.externalTarget || undefined,
+            rel: isBlank ? 'noopener noreferrer' : undefined,
+          },
+          slots.default?.(),
+        )
+      }
+
+      if (classification.kind === 'ignore') {
+        return h(
+          'a',
+          {
+            href: resolved.href || '#',
+            onClick: (event: MouseEvent) => event.preventDefault(),
+          },
+          slots.default?.(),
+        )
+      }
+
+      // child-nav → delegate to real vue-router RouterLink
+      return h(
+        VueRouterLink,
+        {
+          to: props.to,
+          replace: props.replace,
+          activeClass: props.activeClass,
+          exactActiveClass: props.exactActiveClass,
+          ariaCurrentValue: props.ariaCurrentValue,
+        },
+        slots.default
+          ? { default: (scope: unknown) => slots.default?.(scope) }
+          : undefined,
+      )
+    }
+  },
+})
+
+/** @deprecated Use AutoRouterLink instead */
+export const RouterLink = AutoRouterLink

package/src/validate-mount-routes.ts

@@ -0,0 +1,110 @@
+/**
+ * Client-side validator for mountRoute patterns.
+ *
+ * This mirrors the backend (wippy-framework/src/views/page_registry.lua)
+ * validator logic. The backend is the authoritative source — the frontend
+ * re-validates as a defensive safety net for two scenarios:
+ *
+ *   1. A subapp receives `mountRoutes` from `ChildAppConfig` and wants to
+ *      sanity-check them before registering or relying on them (e.g. during
+ *      nested-navigation mount, if a subapp acts as a mini-host).
+ *   2. The host's `syncMountRoutes` calls this to detect conflicts before
+ *      mutating the live Vue Router (fail-fast with a clear error rather
+ *      than leaving the router in a hybrid state).
+ *
+ * The validator is intentionally strict. v1 accepts ONLY the canonical form:
+ *   /:part(.*)*                 root mount
+ *   /<literal>/:part(.*)*       prefix mount (one or more literal segments)
+ *   /<lit1>/<lit2>/:part(.*)*   nested prefix mount
+ *
+ * Literal segments must match `[a-z0-9-]+` (lowercase alphanumerics + hyphens).
+ * The param name `:part` (not `:pathMatch`) matches gen-2-chat's existing
+ * `/c/:id/:part*` convention, so `route.params.part` is a uniform shape
+ * regardless of whether a page was reached via a mount route or via `/c/<id>`.
+ */
+
+export const MOUNT_ROUTE_V1_REGEX = /^\/([a-z0-9-]+(\/[a-z0-9-]+)*\/)?:part\(\.\*\)\*$/
+
+export type MountRouteIssueKind = 'syntax' | 'duplicate'
+
+export interface MountRouteIssue {
+  kind: MountRouteIssueKind
+  mountRoute: string
+  pageId: string
+  conflictingPageId?: string
+}
+
+export class MountRouteValidationError extends Error {
+  constructor(public readonly issues: MountRouteIssue[]) {
+    super(formatMessage(issues))
+    this.name = 'MountRouteValidationError'
+  }
+}
+
+function formatMessage(issues: MountRouteIssue[]): string {
+  const lines: string[] = ['[wippy-fe/router] mountRoute validation failed:', '']
+  for (const issue of issues) {
+    if (issue.kind === 'syntax') {
+      lines.push(
+        `  • Page "${issue.pageId}" has invalid mountRoute "${issue.mountRoute}".`,
+        `    v1 only supports "/<literal>/:part(.*)*" and "/:part(.*)*".`,
+      )
+    }
+    else {
+      lines.push(
+        `  • Pages "${issue.pageId}" and "${issue.conflictingPageId}" both claim`,
+        `    mountRoute "${issue.mountRoute}". Mount routes must be unique.`,
+      )
+    }
+    lines.push('')
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Validate an array of [mountRoute, pageId] tuples.
+ * Returns every issue found (does not stop at first). Empty result = clean.
+ *
+ * Accepts tuples (not a plain object) so duplicate mount routes surface as
+ * separate entries rather than being silently collapsed by object-key dedup.
+ */
+export function validateMountRoutes(
+  entries: Array<[mountRoute: string, pageId: string]>,
+): MountRouteIssue[] {
+  const issues: MountRouteIssue[] = []
+  const seen = new Map<string, string>()
+
+  for (const [mountRoute, pageId] of entries) {
+    if (typeof mountRoute !== 'string' || !MOUNT_ROUTE_V1_REGEX.test(mountRoute)) {
+      issues.push({ kind: 'syntax', mountRoute: String(mountRoute), pageId })
+      continue
+    }
+    const previousOwner = seen.get(mountRoute)
+    if (previousOwner && previousOwner !== pageId) {
+      issues.push({
+        kind: 'duplicate',
+        mountRoute,
+        pageId,
+        conflictingPageId: previousOwner,
+      })
+      continue
+    }
+    seen.set(mountRoute, pageId)
+  }
+
+  return issues
+}
+
+/**
+ * Assert that a map of mountRoutes is valid. Throws MountRouteValidationError
+ * with a detailed message on any issue. Convenience for subapps that want to
+ * fail-fast rather than iterate the issues themselves.
+ */
+export function assertValidMountRoutes(
+  mountRoutes: Record<string, string>,
+): void {
+  const entries: Array<[string, string]> = Object.entries(mountRoutes)
+  const issues = validateMountRoutes(entries)
+  if (issues.length > 0)
+    throw new MountRouteValidationError(issues)
+}