@pathmx/core 0.5.0

package/plugins/runtime/index.ts

@@ -0,0 +1,104 @@
+import { matchesInvalidation } from "../../invalidation.ts"
+import { publicPath } from "../../server/router.ts"
+import { route, type Plugin, type ServerContext } from "../types.ts"
+
+const clientEntry = new URL("./client.ts", import.meta.url)
+const staticClientEntry = new URL("./static-client.ts", import.meta.url)
+const LIVE_HEARTBEAT_INTERVAL = 30_000
+
+function serveLive(
+  ctx: ServerContext,
+  req: Request,
+  route: string,
+  actor?: string,
+  privateResponse = false,
+) {
+  const encoder = new TextEncoder()
+  let unsubscribe: (() => void) | undefined
+  let heartbeat: ReturnType<typeof setInterval> | undefined
+  const cleanup = () => {
+    unsubscribe?.()
+    unsubscribe = undefined
+    if (heartbeat) clearInterval(heartbeat)
+    heartbeat = undefined
+  }
+  const stream = new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode(": connected\n\n"))
+      heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(": keep-alive\n\n"))
+        } catch {
+          cleanup()
+        }
+      }, LIVE_HEARTBEAT_INTERVAL)
+      unsubscribe = ctx.onSync((event) => {
+        if (!matchesInvalidation(event, route, actor)) return
+        try {
+          // EventSource only dispatches events that contain a data field.
+          // Keep it opaque: routing already happened on the server.
+          controller.enqueue(encoder.encode("event: sync\ndata: changed\n\n"))
+        } catch {
+          cleanup()
+        }
+      })
+      req.signal.addEventListener(
+        "abort",
+        () => {
+          cleanup()
+          try {
+            controller.close()
+          } catch {
+            // already closed
+          }
+        },
+        { once: true },
+      )
+    },
+    cancel() {
+      cleanup()
+    },
+  })
+  const headers = new Headers({
+    "Content-Type": "text/event-stream",
+    "Cache-Control": privateResponse ? "private, no-store" : "no-cache",
+    Connection: "keep-alive",
+  })
+  if (privateResponse) headers.set("Vary", "Cookie")
+  return new Response(stream, { headers })
+}
+
+export function RuntimePlugin(): Plugin {
+  return {
+    id: "runtime",
+    name: "RuntimePlugin",
+    routes: [
+      route.get("live", async (ctx) => {
+        const { request, url } = ctx
+        const requested = url.searchParams.get("route")
+        const source = requested ? ctx.resolve(requested) : undefined
+        if (!source) {
+          return new Response("Unknown live route.", { status: 400 })
+        }
+        const session = await ctx.session()
+        const access = await ctx.readAccess(source)
+        if (access === "denied") {
+          return new Response("Not Found", { status: 404 })
+        }
+        return serveLive(
+          ctx,
+          request,
+          publicPath(source),
+          session.type === "authenticated" ? session.actor.id : undefined,
+          access === "private" || session.type === "authenticated",
+        )
+      }),
+    ],
+    async documentAssets(ctx, app) {
+      await ctx.addBrowserBundle(
+        app.runtime.target === "static" ? staticClientEntry : clientEntry,
+        "runtime",
+      )
+    },
+  }
+}

package/plugins/runtime/live.ts

@@ -0,0 +1,51 @@
+export type LiveSubscription = {
+  bind(): void
+  close(): void
+}
+
+export type LiveSync = () => void | Promise<void>
+export type LiveSubscriptionFactory = (onSync: LiveSync) => LiveSubscription
+
+function liveTarget() {
+  const view = document.querySelector("[data-pmx-view]")
+  if (!(view instanceof HTMLElement)) return
+  const route = view.dataset.pmxRoute
+  if (!route) return
+  return { route }
+}
+
+export function createLiveSubscription(onSync: LiveSync): LiveSubscription {
+  let connection: { key: string; source: EventSource } | undefined
+
+  return {
+    bind() {
+      const target = liveTarget()
+      if (!target) return
+      const key = target.route
+      if (connection?.key === key) return
+
+      connection?.source.close()
+      const url = new URL("/api/runtime/live", location.href)
+      url.searchParams.set("route", target.route)
+      const source = new EventSource(url)
+      let interrupted = false
+      source.addEventListener("error", () => {
+        interrupted = true
+      })
+      source.addEventListener("open", () => {
+        if (!interrupted || connection?.source !== source) return
+        // Reconcile what may have changed while offline. The runtime refresh
+        // will request a reload only when browser assets are incompatible.
+        interrupted = false
+        void onSync()
+      })
+      source.addEventListener("sync", () => void onSync())
+      connection = { key, source }
+    },
+
+    close() {
+      connection?.source.close()
+      connection = undefined
+    },
+  }
+}

package/plugins/runtime/navigation.ts

@@ -0,0 +1,113 @@
+import { reportRuntimeError } from "./error.ts"
+import { navigationViewTransitionTypes } from "./view-transition.ts"
+import { publicationContains, publicationPath } from "./publication.ts"
+
+export type NavigationVisit = (
+  destination: URL,
+  options: {
+    type: "navigation" | "traverse"
+    from: URL
+    signal: AbortSignal
+    viewTransition: boolean
+    viewTransitionTypes: readonly string[]
+  },
+) => Promise<{ type: "rendered" } | { type: "native"; url: URL }>
+
+type BrowserNavigateEvent = Event & {
+  canIntercept: boolean
+  destination: { url: string; sameDocument: boolean; index?: number }
+  downloadRequest: string | null
+  formData: FormData | null
+  hashChange: boolean
+  hasUAVisualTransition: boolean
+  navigationType: "push" | "reload" | "replace" | "traverse"
+  signal: AbortSignal
+  sourceElement: Element | null
+  intercept(options: { handler(): Promise<void> }): void
+}
+
+type BrowserNavigation = EventTarget & {
+  currentEntry?: { index: number }
+  addEventListener(
+    type: "navigate",
+    listener: (event: BrowserNavigateEvent) => void,
+  ): void
+  removeEventListener(
+    type: "navigate",
+    listener: (event: BrowserNavigateEvent) => void,
+  ): void
+}
+
+function navigationApi() {
+  return (window as Window & { navigation?: BrowserNavigation }).navigation
+}
+
+function shouldIntercept(event: BrowserNavigateEvent) {
+  if (!event.canIntercept || event.hashChange) return false
+  if (event.destination.sameDocument && event.navigationType !== "traverse") {
+    return false
+  }
+  if (event.downloadRequest !== null || event.formData !== null) return false
+  if (event.navigationType === "reload") return false
+
+  const destination = new URL(event.destination.url)
+  if (destination.origin !== location.origin) return false
+  if (!publicationContains(destination.pathname)) return false
+  if (destination.pathname.startsWith(publicationPath("/.pmx/"))) return false
+  if (destination.pathname.startsWith(publicationPath("/actions/")))
+    return false
+  if (destination.pathname.endsWith(".md")) return false
+  if (event.sourceElement?.closest("[data-pmx-reload], [rel~='external']")) {
+    return false
+  }
+  return true
+}
+
+export function installNavigation(visit: NavigationVisit) {
+  const browserNavigation = navigationApi()
+  if (!browserNavigation) return
+
+  const navigate = (event: BrowserNavigateEvent) => {
+    if (!shouldIntercept(event)) return
+    const from = new URL(location.href)
+    const type = event.navigationType === "traverse" ? "traverse" : "navigation"
+    // Indexes are only reliable here. After intercept, currentEntry is the destination.
+    const viewTransitionTypes = navigationViewTransitionTypes({
+      type,
+      currentIndex: browserNavigation.currentEntry?.index,
+      destinationIndex: event.destination.index,
+    })
+    event.intercept({
+      async handler() {
+        try {
+          const result = await visit(new URL(event.destination.url), {
+            type,
+            from,
+            signal: event.signal,
+            viewTransition: !event.hasUAVisualTransition,
+            viewTransitionTypes,
+          })
+          if (result.type === "rendered" || event.signal.aborted) return
+          browserNavigation.removeEventListener("navigate", navigate)
+          location.replace(result.url)
+        } catch (error) {
+          if (event.signal.aborted) return
+          reportRuntimeError({
+            type,
+            outcome: "native",
+            message:
+              "The enhanced navigation failed. Loading the destination normally.",
+          })
+          console.error(
+            "PathMX navigation failed; loading the document.",
+            error,
+          )
+          browserNavigation.removeEventListener("navigate", navigate)
+          location.reload()
+        }
+      },
+    })
+  }
+
+  browserNavigation.addEventListener("navigate", navigate)
+}

package/plugins/runtime/pending.ts

@@ -0,0 +1,53 @@
+import type { RenderType } from "./document.ts"
+
+export type PendingTarget = {
+  form: HTMLFormElement
+  submitter: HTMLElement | null
+}
+
+export type PendingDetail = {
+  pending: boolean
+  type: RenderType
+}
+
+function dispatchPending(detail: PendingDetail) {
+  document.dispatchEvent(
+    new CustomEvent<PendingDetail>("pmx:pending", { detail }),
+  )
+}
+
+function markViewBusy(busy: boolean) {
+  const view = document.querySelector("[data-pmx-view]")
+  if (!(view instanceof HTMLElement)) return
+  if (busy) view.setAttribute("aria-busy", "true")
+  else view.removeAttribute("aria-busy")
+}
+
+export function startPending(type: RenderType, target?: PendingTarget) {
+  const root = document.documentElement
+  const previousSubmitterState =
+    target?.submitter?.getAttribute("aria-disabled")
+
+  root.dataset.pmxPending = type
+  markViewBusy(true)
+  target?.form.setAttribute("data-pmx-pending", "")
+  target?.submitter?.setAttribute("data-pmx-pending", "")
+  target?.submitter?.setAttribute("aria-disabled", "true")
+  dispatchPending({ pending: true, type })
+
+  let finished = false
+  return () => {
+    if (finished) return
+    finished = true
+    if (root.dataset.pmxPending === type) delete root.dataset.pmxPending
+    markViewBusy(false)
+    target?.form.removeAttribute("data-pmx-pending")
+    target?.submitter?.removeAttribute("data-pmx-pending")
+    if (previousSubmitterState == null) {
+      target?.submitter?.removeAttribute("aria-disabled")
+    } else {
+      target?.submitter?.setAttribute("aria-disabled", previousSubmitterState)
+    }
+    dispatchPending({ pending: false, type })
+  }
+}

package/plugins/runtime/publication.ts

@@ -0,0 +1,19 @@
+export function publicationBasePath() {
+  const value = document.documentElement.dataset.pmxBase
+  return value?.startsWith("/") ? value : "/"
+}
+
+export function publicationPath(pathname: string) {
+  const basePath = publicationBasePath()
+  if (basePath === "/") return pathname
+  return pathname === "/" ? basePath : `${basePath}${pathname}`
+}
+
+export function publicationContains(pathname: string) {
+  const basePath = publicationBasePath()
+  return (
+    basePath === "/" ||
+    pathname === basePath ||
+    pathname.startsWith(`${basePath}/`)
+  )
+}

package/plugins/runtime/start.ts

@@ -0,0 +1,177 @@
+import {
+  fetchPathMXDocument,
+  PathMXReloadRequiredError,
+  readPathMXDocument,
+  reconcilePathMXDocument,
+  type RenderType,
+} from "./document.ts"
+import type { LiveSubscriptionFactory } from "./live.ts"
+import { installNavigation, type NavigationVisit } from "./navigation.ts"
+import { installViewportChrome } from "./viewport.ts"
+import { startPending, type PendingTarget } from "./pending.ts"
+import { reportRuntimeError } from "./error.ts"
+import { installHeadingLinks } from "./heading-links.ts"
+
+type ActiveLoad = {
+  controller: AbortController
+  signal: AbortSignal
+  type: RenderType
+  finishPending: () => void
+}
+
+type RuntimeOptions = Readonly<{
+  actions?: RuntimeActionInstaller
+  live: LiveSubscriptionFactory
+}>
+
+type RuntimeActionLoad = Readonly<{
+  signal: AbortSignal
+  apply(response: Response, from: URL): Promise<void>
+  finish(): void
+}>
+
+export type RuntimeActionInstaller = (runtime: {
+  isNavigating(): boolean
+  begin(target: PendingTarget): RuntimeActionLoad | undefined
+}) => void
+
+export function startRuntime(options: RuntimeOptions) {
+  let active: ActiveLoad | undefined
+  let liveQueued = false
+
+  function begin(
+    type: RenderType,
+    signal?: AbortSignal,
+    target?: PendingTarget,
+  ) {
+    active?.finishPending()
+    active?.controller.abort()
+    const controller = new AbortController()
+    const load: ActiveLoad = {
+      controller,
+      signal: signal
+        ? AbortSignal.any([controller.signal, signal])
+        : controller.signal,
+      type,
+      finishPending: startPending(type, target),
+    }
+    active = load
+    return load
+  }
+
+  function finish(load: ActiveLoad) {
+    if (active !== load) return
+    active = undefined
+    load.finishPending()
+    if (liveQueued) queueMicrotask(runLiveRefresh)
+  }
+
+  function isCurrent(load: ActiveLoad) {
+    return active === load && !load.signal.aborted
+  }
+
+  function isNavigating() {
+    return active?.type === "navigation" || active?.type === "traverse"
+  }
+
+  function sameRequestUrl(left: URL, right: URL) {
+    return (
+      left.origin === right.origin &&
+      left.pathname === right.pathname &&
+      left.search === right.search
+    )
+  }
+
+  async function apply(
+    load: ActiveLoad,
+    loaded: Awaited<ReturnType<typeof fetchPathMXDocument>>,
+    settings: {
+      from: URL
+      viewTransition: boolean
+      viewTransitionTypes?: readonly string[]
+    },
+  ) {
+    if (!isCurrent(load)) return
+    await reconcilePathMXDocument(loaded, {
+      type: load.type,
+      from: settings.from,
+      viewTransition: settings.viewTransition,
+      viewTransitionTypes: settings.viewTransitionTypes ?? [],
+    })
+    live.bind()
+  }
+
+  const visit: NavigationVisit = async (destination, settings) => {
+    const load = begin(settings.type, settings.signal)
+    try {
+      const loaded = await fetchPathMXDocument(destination, load.signal)
+      if (!sameRequestUrl(loaded.responseUrl, destination)) {
+        return { type: "native", url: loaded.responseUrl }
+      }
+      await apply(load, loaded, settings)
+      return { type: "rendered" }
+    } finally {
+      finish(load)
+    }
+  }
+
+  function refreshLive() {
+    liveQueued = true
+    if (!active) queueMicrotask(runLiveRefresh)
+  }
+
+  async function runLiveRefresh() {
+    if (active || !liveQueued) return
+    liveQueued = false
+    const load = begin("live")
+    const url = new URL(location.href)
+    try {
+      const loaded = await fetchPathMXDocument(url, load.signal, "no-store")
+      await apply(load, loaded, { from: url, viewTransition: false })
+    } catch (error) {
+      if (load.signal.aborted) return
+      if (error instanceof PathMXReloadRequiredError) {
+        liveQueued = false
+        location.reload()
+        return
+      }
+      reportRuntimeError({
+        type: "live",
+        outcome: "stale",
+        message:
+          "The live refresh failed. The current page remains available and may be stale.",
+      })
+      console.error("PathMX live refresh failed.", error)
+    } finally {
+      finish(load)
+    }
+  }
+
+  const live = options.live(refreshLive)
+
+  options.actions?.({
+    isNavigating,
+    begin(target) {
+      if (active?.type === "action") return
+      const load = begin("action", undefined, target)
+      return {
+        signal: load.signal,
+        async apply(response, from) {
+          if (!sameRequestUrl(from, new URL(location.href))) return
+          const loaded = await readPathMXDocument(response, from)
+          await apply(load, loaded, { from, viewTransition: false })
+        },
+        finish() {
+          finish(load)
+        },
+      }
+    },
+  })
+
+  live.bind()
+  installHeadingLinks()
+  installViewportChrome()
+  installNavigation(visit)
+  addEventListener("pagehide", () => live.close())
+  addEventListener("pageshow", () => live.bind())
+}

package/plugins/runtime/static-client.ts

@@ -0,0 +1,6 @@
+import { createPollingLiveSubscription } from "./static-live.ts"
+import { startRuntime } from "./start.ts"
+
+startRuntime({
+  live: createPollingLiveSubscription,
+})