@pathmx/core 0.5.0

package/plugins/runtime/static-live.ts

@@ -0,0 +1,188 @@
+import type { LiveSubscription, LiveSubscriptionFactory } from "./live.ts"
+import { publicationPath } from "./publication.ts"
+
+const POLL_INTERVAL = 30_000
+const MAX_BACKOFF = 5 * 60_000
+
+type BuildRecord = Readonly<{
+  version: string
+  pages: string
+}>
+
+type PageMap = Readonly<{
+  version: 1
+  build: string
+  pages: Readonly<Record<string, string>>
+}>
+
+function currentPage() {
+  return document.documentElement.dataset.pmxPage
+}
+
+function currentRoute() {
+  const view = document.querySelector<HTMLElement>("[data-pmx-view]")
+  return view?.dataset.pmxRoute || location.pathname
+}
+
+function isBuildRecord(value: unknown): value is BuildRecord {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "version" in value &&
+    typeof value.version === "string" &&
+    value.version.length > 0 &&
+    "pages" in value &&
+    typeof value.pages === "string" &&
+    value.pages.length > 0
+  )
+}
+
+function isPageMap(value: unknown, build: string): value is PageMap {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("version" in value) ||
+    value.version !== 1 ||
+    !("build" in value) ||
+    value.build !== build ||
+    !("pages" in value) ||
+    typeof value.pages !== "object" ||
+    value.pages === null
+  ) {
+    return false
+  }
+  return Object.values(value.pages).every(
+    (leaf) => typeof leaf === "string" && leaf.length > 0,
+  )
+}
+
+function jitter(delay: number) {
+  return Math.round(delay * (0.9 + Math.random() * 0.2))
+}
+
+export const createPollingLiveSubscription: LiveSubscriptionFactory = (
+  onSync,
+): LiveSubscription => {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let controller: AbortController | undefined
+  let loaded: { record: BuildRecord; map: PageMap } | undefined
+  let running = false
+  let failures = 0
+
+  const schedule = (delay = POLL_INTERVAL) => {
+    if (!running || timer || document.visibilityState === "hidden") return
+    timer = setTimeout(() => {
+      timer = undefined
+      void check()
+    }, jitter(delay))
+  }
+
+  const loadPageMap = async (record: BuildRecord, signal: AbortSignal) => {
+    if (
+      loaded?.record.version === record.version &&
+      loaded.record.pages === record.pages
+    ) {
+      return loaded.map
+    }
+    const url = new URL(record.pages, location.href)
+    if (url.origin !== location.origin) {
+      throw new Error("PathMX page map must use the publication origin.")
+    }
+    const response = await fetch(url, {
+      cache: "force-cache",
+      headers: { Accept: "application/json" },
+      signal,
+    })
+    if (!response.ok) {
+      throw new Error(`Page map returned ${response.status}.`)
+    }
+    const map: unknown = await response.json()
+    if (!isPageMap(map, record.version)) {
+      throw new Error("Invalid PathMX page map.")
+    }
+    loaded = { record, map }
+    return map
+  }
+
+  const pageIsCurrent = async (record: BuildRecord, signal: AbortSignal) => {
+    const map = await loadPageMap(record, signal)
+    return map.pages[currentRoute()] === currentPage()
+  }
+
+  const check = async () => {
+    if (!running) return
+    if (document.visibilityState === "hidden") return
+
+    controller?.abort()
+    const request = new AbortController()
+    controller = request
+    try {
+      const response = await fetch(
+        new URL(publicationPath("/.pmx/build.json"), location.origin),
+        {
+          cache: "no-store",
+          headers: { Accept: "application/json" },
+          signal: request.signal,
+        },
+      )
+      if (!response.ok) {
+        throw new Error(`Build check returned ${response.status}.`)
+      }
+      const record: unknown = await response.json()
+      if (!isBuildRecord(record)) {
+        throw new Error("Invalid PathMX build record.")
+      }
+      if (await pageIsCurrent(record, request.signal)) {
+        failures = 0
+      } else {
+        await onSync()
+        failures = (await pageIsCurrent(record, request.signal))
+          ? 0
+          : failures + 1
+      }
+    } catch (error) {
+      if (!request.signal.aborted) failures++
+    } finally {
+      if (controller === request) controller = undefined
+      const backoff = Math.min(
+        POLL_INTERVAL * 2 ** Math.min(failures, 4),
+        MAX_BACKOFF,
+      )
+      schedule(backoff)
+    }
+  }
+
+  const onVisibilityChange = () => {
+    if (!running) return
+    if (timer) clearTimeout(timer)
+    timer = undefined
+    if (document.visibilityState !== "visible") {
+      controller?.abort()
+      return
+    }
+    schedule(0)
+  }
+  document.addEventListener("visibilitychange", onVisibilityChange)
+
+  return {
+    bind() {
+      if (!running) {
+        running = true
+        schedule()
+        return
+      }
+      if (controller) return
+      if (timer) clearTimeout(timer)
+      timer = undefined
+      schedule(0)
+    },
+
+    close() {
+      running = false
+      if (timer) clearTimeout(timer)
+      timer = undefined
+      controller?.abort()
+      controller = undefined
+    },
+  }
+}

package/plugins/runtime/view-transition.ts

@@ -0,0 +1,72 @@
+export const viewTransitionType = {
+  navigation: "pmx-navigation",
+  traverse: "pmx-traverse",
+  forward: "pmx-forward",
+  back: "pmx-back",
+} as const
+
+export type ViewTransitionType =
+  (typeof viewTransitionType)[keyof typeof viewTransitionType]
+
+export type ViewTransitionNavigation = {
+  type: "navigation" | "traverse"
+  currentIndex?: number
+  destinationIndex?: number
+}
+
+type ViewTransitionUpdate = () => void | Promise<void>
+
+type StartViewTransition = {
+  (update?: ViewTransitionUpdate): ViewTransition
+  (options: { update?: ViewTransitionUpdate; types?: string[] }): ViewTransition
+}
+
+function historyIndex(value: number | undefined) {
+  return value == null || value < 0 ? undefined : value
+}
+
+export function navigationViewTransitionTypes(
+  navigation: ViewTransitionNavigation,
+): readonly ViewTransitionType[] {
+  const renderType = viewTransitionType[navigation.type]
+  if (navigation.type !== "traverse") {
+    return [renderType, viewTransitionType.forward]
+  }
+
+  const from = historyIndex(navigation.currentIndex)
+  const to = historyIndex(navigation.destinationIndex)
+  if (from == null || to == null || from === to) return [renderType]
+  return [
+    renderType,
+    to < from ? viewTransitionType.back : viewTransitionType.forward,
+  ]
+}
+
+function supportsTypedStart() {
+  try {
+    return CSS.supports("selector(:active-view-transition-type(pmx-forward))")
+  } catch {
+    return false
+  }
+}
+
+export function startPathMXViewTransition(
+  update: ViewTransitionUpdate,
+  types: readonly string[],
+) {
+  const start = document.startViewTransition.bind(
+    document,
+  ) as StartViewTransition
+  const listed = [...types]
+  const transition =
+    listed.length && supportsTypedStart()
+      ? start({ update, types: listed })
+      : start(update)
+  const set = (
+    transition as ViewTransition & { types?: { add(type: string): void } }
+  ).types
+  if (set) {
+    for (const type of listed) set.add(type)
+  }
+  return transition
+}

package/plugins/runtime/viewport.ts

@@ -0,0 +1,110 @@
+const HEADER_SELECTOR = "[data-pmx-sticky-header]"
+const HIDE_THRESHOLD = 12
+
+type ViewportChrome = {
+  header: HTMLElement
+  observer: ResizeObserver
+  height: number
+  lastScrollY: number
+  direction: -1 | 0 | 1
+  directionDistance: number
+  hidden: boolean
+  sticky: boolean
+}
+
+function setInset(height: number) {
+  document.documentElement.style.setProperty(
+    "--pmx-viewport-inset-block-start",
+    `${height}px`,
+  )
+}
+
+function setHidden(chrome: ViewportChrome, hidden: boolean) {
+  chrome.hidden = hidden
+  chrome.header.toggleAttribute("data-pmx-hidden", hidden)
+}
+
+function measure(chrome: ViewportChrome) {
+  chrome.sticky = getComputedStyle(chrome.header).position === "sticky"
+  chrome.height = chrome.sticky
+    ? chrome.header.getBoundingClientRect().height
+    : 0
+  setInset(chrome.height)
+  if (!chrome.sticky) setHidden(chrome, false)
+}
+
+function createChrome(header: HTMLElement): ViewportChrome {
+  const chrome: ViewportChrome = {
+    header,
+    observer: new ResizeObserver(() => measure(chrome)),
+    height: 0,
+    lastScrollY: Math.max(0, scrollY),
+    direction: 0,
+    directionDistance: 0,
+    hidden: false,
+    sticky: false,
+  }
+  chrome.observer.observe(header)
+  measure(chrome)
+  return chrome
+}
+
+/** Coordinates opt-in sticky chrome with shared viewport CSS variables. */
+export function installViewportChrome() {
+  let chrome: ViewportChrome | undefined
+  let listening = false
+
+  let scrollFrame = 0
+  const onScroll = () => {
+    if (!chrome || scrollFrame) return
+    scrollFrame = requestAnimationFrame(() => {
+      scrollFrame = 0
+      if (!chrome?.sticky) return
+
+      const current = Math.max(0, scrollY)
+      const delta = current - chrome.lastScrollY
+      chrome.lastScrollY = current
+      if (!delta) return
+
+      const direction = delta > 0 ? 1 : -1
+      if (direction !== chrome.direction) {
+        chrome.direction = direction
+        chrome.directionDistance = 0
+      }
+      chrome.directionDistance += Math.abs(delta)
+
+      if (current <= chrome.height || chrome.header.matches(":focus-within")) {
+        setHidden(chrome, false)
+      } else if (chrome.directionDistance >= HIDE_THRESHOLD) {
+        setHidden(chrome, direction > 0)
+        chrome.directionDistance = 0
+      }
+    })
+  }
+
+  const listen = (enabled: boolean) => {
+    if (listening === enabled) return
+    listening = enabled
+    if (enabled) addEventListener("scroll", onScroll, { passive: true })
+    else removeEventListener("scroll", onScroll)
+  }
+
+  const reconcile = () => {
+    const header = document.querySelector<HTMLElement>(HEADER_SELECTOR)
+    if (chrome?.header === header) {
+      setHidden(chrome, chrome.hidden)
+      measure(chrome)
+      return
+    }
+    chrome?.observer.disconnect()
+    chrome = header ? createChrome(header) : undefined
+    if (!chrome) setInset(0)
+    listen(chrome != null)
+  }
+
+  addEventListener("resize", () => chrome && measure(chrome))
+  document.addEventListener("pmx:render", () =>
+    requestAnimationFrame(reconcile),
+  )
+  reconcile()
+}

package/plugins/schema.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from "./types.ts"
+
+/** Baseline application Schema. Feature Plugins refine the node types they own. */
+export function SchemaPlugin(): Plugin {
+  return {
+    id: "schema",
+    schema: {
+      sources: {
+        page: {
+          label: "Page",
+          description: "A general rendered document.",
+          icon: "file-text",
+          color: "slate",
+        },
+        map: {
+          label: "Map",
+          description: "Source-type schema and presentation metadata.",
+          icon: "map",
+          color: "teal",
+        },
+      },
+    },
+  }
+}

package/plugins/scripts.ts

@@ -0,0 +1,140 @@
+import { cachedRouteTargets } from "../invalidation.ts"
+import { parseLinks, type Source, type SourceLink } from "../source/index.ts"
+import { directiveDefinition } from "./directive-definitions.ts"
+import type { DependencyContext, Plugin } from "./types.ts"
+
+const EXTERNAL = /^[a-z][a-z\d+.-]*:/i
+type AuthoredScript = Readonly<{
+  type: "script"
+  source: string
+  module: true
+}>
+
+function resolveTarget(source: Source, target: string) {
+  return target.startsWith("/")
+    ? target
+    : new URL(target, `file://${source.path}`).pathname
+}
+
+function scriptLinks(links: readonly SourceLink[]) {
+  return links.filter((link) => link.directive?.name === "script")
+}
+
+function resolveScript(
+  source: Source,
+  link: SourceLink,
+): AuthoredScript | undefined {
+  if (link.directive?.name !== "script") return
+  const raw = link.href.split("#")[0]?.split("?")[0] ?? ""
+  if (
+    !raw ||
+    EXTERNAL.test(raw) ||
+    raw.startsWith("//") ||
+    raw.startsWith("~/")
+  )
+    return
+  const sourcePath = resolveTarget(source, raw)
+  if (!sourcePath.endsWith(".js")) return
+  return {
+    type: "script",
+    source: sourcePath,
+    module: true,
+  }
+}
+
+function pushUnique(assets: AuthoredScript[], asset: AuthoredScript) {
+  if (assets.some((item) => item.source === asset.source)) return
+  assets.push(asset)
+}
+
+function addScriptDependency(
+  dependencies: DependencyContext,
+  asset: AuthoredScript,
+) {
+  dependencies.depend({ type: "source", path: asset.source })
+}
+
+function sourceScriptLinks(source: Source) {
+  return source.blocks.length
+    ? source.blocks.flatMap((block) => block.links)
+    : source.links
+}
+
+function globalScripts(source: Source, links: readonly SourceLink[]) {
+  const assets: AuthoredScript[] = []
+  for (const link of scriptLinks(links)) {
+    if (!link.directive?.qualifiers.includes("global")) continue
+    const asset = resolveScript(source, link)
+    if (asset) pushUnique(assets, asset)
+  }
+  return assets
+}
+
+function scriptSignature(assets: readonly AuthoredScript[]) {
+  return assets.map((asset) => asset.source).join("\n")
+}
+
+function authoredGlobalSignature(source?: Source) {
+  return scriptSignature(
+    source ? globalScripts(source, parseLinks(source.body)) : [],
+  )
+}
+
+export function ScriptsPlugin(): Plugin {
+  const global = new Map<string, AuthoredScript[]>()
+
+  return {
+    id: "scripts",
+
+    index(source) {
+      const assets = globalScripts(source, sourceScriptLinks(source))
+      if (assets.length) global.set(source.path, assets)
+      else global.delete(source.path)
+    },
+
+    unindex(sourcePath) {
+      global.delete(sourcePath)
+    },
+
+    precompile(markdown, ctx) {
+      const scripts = scriptLinks(ctx.block?.links ?? ctx.source.links)
+      if (!scripts.length) return markdown
+      let current = markdown
+      for (const link of scripts) {
+        current = current.replace(directiveDefinition("script", link.href), "")
+      }
+      return current
+    },
+
+    invalidate({ before, after }, app) {
+      if (authoredGlobalSignature(before) === authoredGlobalSignature(after))
+        return
+      const pages = app.sources.builtPages()
+      return {
+        sourceIds: pages.map((page) => page.sourceId),
+        targets: cachedRouteTargets(pages),
+      }
+    },
+
+    page(html, ctx) {
+      for (const assets of global.values()) {
+        for (const asset of assets) addScriptDependency(ctx, asset)
+      }
+      for (const link of scriptLinks(ctx.source.links)) {
+        if (link.directive?.qualifiers.includes("global")) continue
+        const asset = resolveScript(ctx.source, link)
+        if (asset) {
+          ctx.addAsset(asset)
+          addScriptDependency(ctx, asset)
+        }
+      }
+      return html
+    },
+
+    documentAssets(ctx) {
+      for (const origin of [...global.keys()].sort()) {
+        for (const asset of global.get(origin) ?? []) ctx.addAsset(asset)
+      }
+    },
+  }
+}