@pathmx/core 0.5.0

package/host/source-sync.ts

@@ -0,0 +1,254 @@
+import { dependencyKey } from "../dependencies.ts"
+import { RouteInvalidations, type RouteInvalidation } from "../invalidation.ts"
+import * as queryInvalidation from "../query/invalidation.ts"
+import type { CommitResult, SourceChangeSet } from "../repository.ts"
+import type { Source } from "../source/index.ts"
+import type { SourceTransition } from "../plugins/types.ts"
+import type { PageCompiler } from "./compiler.ts"
+import type { Engine } from "./engine.ts"
+import type { PluginHost } from "./plugin-host.ts"
+
+type RefreshTransition = SourceTransition & {
+  path: string
+}
+
+/** Owns serialized source changes, recompilation, and route invalidation. */
+export class SourceSynchronizer {
+  private listeners = new Set<(event: RouteInvalidation) => void>()
+  private commitQueue: Promise<void> = Promise.resolve()
+
+  constructor(
+    private engine: Engine,
+    private plugins: PluginHost,
+    private compiler: PageCompiler,
+  ) {}
+
+  onSync(listener: (event: RouteInvalidation) => void) {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  private emit(event: RouteInvalidation) {
+    if (!event.targets.length) return
+    for (const listener of this.listeners) listener(event)
+  }
+
+  private referrerPaths(path: string) {
+    return this.engine.graph.linksTo(path).map((edge) => edge.from)
+  }
+
+  private addPageInvalidations(
+    invalidations: RouteInvalidations,
+    pagePaths: Iterable<string>,
+  ) {
+    for (const pagePath of pagePaths) {
+      const page = this.compiler.pageCache.get(pagePath)
+      if (page) invalidations.add(page.route)
+    }
+  }
+
+  private applyPluginInvalidations(
+    dirty: Set<string>,
+    invalidations: RouteInvalidations,
+    transition: SourceTransition,
+  ) {
+    for (const invalidation of this.plugins.invalidations(
+      transition,
+      this.engine,
+    )) {
+      const dependencies = [...(invalidation.dependencies ?? [])]
+      queryInvalidation.dependencies(this.engine, invalidations, dependencies)
+      for (const dependency of dependencies) {
+        for (const pagePath of this.compiler.dependentsOf(
+          dependencyKey(dependency),
+        )) {
+          dirty.add(pagePath)
+        }
+      }
+      for (const sourceId of invalidation.sourceIds ?? []) {
+        const source = this.engine.repo.get(sourceId)
+        if (source && this.compiler.isPage(source)) dirty.add(source.path)
+      }
+      for (const target of invalidation.targets ?? []) {
+        if (target.type === "actor") {
+          invalidations.addActorTargets(target.actors)
+        } else if (target.actors == null) invalidations.add(target.route)
+        else invalidations.addActors(target.route, target.actors)
+      }
+    }
+  }
+
+  private async rebuildGraph() {
+    await this.engine.perf.measureAsync("graph.rebuild", () =>
+      this.engine.graph.rebuild(),
+    )
+  }
+
+  private async refreshTransitions(transitions: RefreshTransition[]) {
+    return this.engine.perf.measureAsync(
+      "notify",
+      async () => {
+        const invalidations = new RouteInvalidations()
+        const dirty = new Set<string>()
+
+        for (const transition of transitions) {
+          this.applyPluginInvalidations(dirty, invalidations, transition)
+          const graphPath = this.engine.repo.graphPath(transition.path)
+          this.engine.log.debug("rebuild", { path: graphPath })
+          const cached = this.compiler.pageCache.get(graphPath)
+          if (cached) invalidations.add(cached.route)
+          for (const path of this.referrerPaths(graphPath)) dirty.add(path)
+          for (const path of this.compiler.dependentsOf(graphPath))
+            dirty.add(path)
+
+          if (!transition.after) {
+            queryInvalidation.source(
+              this.engine,
+              invalidations,
+              transition.before,
+              transition.after,
+              graphPath,
+            )
+            if (transition.before) {
+              this.engine.clearAuthorityError(transition.before.id)
+            }
+            this.engine.forgetNode(graphPath)
+            this.compiler.forgetCompiled(graphPath)
+            continue
+          }
+
+          this.engine.indexSource(transition.after, true)
+          queryInvalidation.source(
+            this.engine,
+            invalidations,
+            transition.before,
+            transition.after,
+            graphPath,
+          )
+          if (this.compiler.isPage(transition.after)) {
+            dirty.add(transition.after.path)
+          } else {
+            this.compiler.pageCache.delete(transition.after.path)
+          }
+        }
+
+        await this.rebuildGraph()
+        for (const transition of transitions) {
+          for (const path of this.referrerPaths(transition.path))
+            dirty.add(path)
+        }
+        await this.compiler.recompilePages(dirty)
+        this.addPageInvalidations(invalidations, dirty)
+        return invalidations.event()
+      },
+      transitions.map((transition) => transition.path).join(","),
+    )
+  }
+
+  dropNode(nodePath: string) {
+    const source =
+      this.engine.repo.atPath(nodePath) ?? this.engine.repo.get(nodePath)
+    const path = source?.path ?? this.engine.repo.graphPath(nodePath)
+    this.engine.repo.remove(path)
+    this.engine.forgetNode(path)
+    this.compiler.forgetCompiled(path)
+  }
+
+  commit(changeSet: SourceChangeSet) {
+    return this.commitPrepared(async () => changeSet)
+  }
+
+  /** Serialize intent preparation, durable commit, refresh, and publication. */
+  commitPrepared(prepare: () => Promise<SourceChangeSet>) {
+    const pending = this.commitQueue.then(async () => {
+      const changeSet = await prepare()
+      if (!changeSet.changes.length) return { applied: [] }
+      return this.commitNow(changeSet)
+    })
+    this.commitQueue = pending.then(
+      () => undefined,
+      () => undefined,
+    )
+    return pending
+  }
+
+  private async commitNow(changeSet: SourceChangeSet) {
+    const before = new Map(
+      changeSet.changes.map((change) => {
+        const path = this.engine.repo.graphPath(change.path)
+        return [path, this.engine.repo.atPath(path)] as const
+      }),
+    )
+    const result = await this.engine.repo.commit(changeSet)
+    await this.refresh(result, before)
+    if (result.error) throw result.error
+    return result
+  }
+
+  async refresh(
+    result: CommitResult,
+    before = new Map<string, Source | undefined>(),
+  ) {
+    const event = await this.refreshTransitions(
+      result.applied.map((change) => {
+        const path = this.engine.repo.graphPath(change.path)
+        return {
+          path,
+          before: before.get(path),
+          after: this.engine.repo.atPath(path),
+        }
+      }),
+    )
+    this.emit(event)
+  }
+
+  async syncSource(path: string) {
+    const graphPath = this.engine.repo.graphPath(path)
+    const previous = this.engine.repo.atPath(graphPath)
+    const result = await this.engine.repo.upsert(path, { onError: "preserve" })
+    if (result.type === "error") {
+      this.engine.log.error("source.parse", {
+        path: graphPath,
+        message: result.error.message,
+      })
+      return
+    }
+    const source = result.type === "updated" ? result.source : undefined
+    if (source && source.content === previous?.content) return
+    const event = await this.refreshTransitions([
+      { path: graphPath, before: previous, after: source },
+    ])
+    this.emit(event)
+  }
+
+  invalidateAsset(path: string) {
+    this.invalidateAssets([path])
+  }
+
+  invalidateAssets(paths: Iterable<string>) {
+    const changed = [...paths]
+    this.engine.bumpAssetRevisions(changed)
+    const invalidations = new RouteInvalidations()
+    for (const path of changed) {
+      const graphPath = this.engine.repo.graphPath(path)
+      this.addPageInvalidations(
+        invalidations,
+        this.compiler.dependentsOf(graphPath),
+      )
+    }
+    this.emit(invalidations.event())
+  }
+
+  async syncFromStorage(relPath: string) {
+    return this.engine.perf.measureAsync(
+      "sync-from-storage",
+      async () => {
+        if (!this.engine.repo.storagePath(relPath)) return
+        await this.syncSource(this.engine.repo.graphPath(relPath).slice(1))
+      },
+      relPath,
+    )
+  }
+}

package/html-attributes.ts

@@ -0,0 +1,15 @@
+import { decodeHtmlEntities } from "./util.ts"
+
+const ATTRIBUTE =
+  /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g
+
+/** @internal Parse the constrained attributes accepted by authored empty elements. */
+export function parseHtmlAttributes(raw: string | undefined) {
+  const attrs: Record<string, string> = {}
+  for (const match of raw?.matchAll(ATTRIBUTE) ?? []) {
+    const name = match[1]!.toLowerCase()
+    if (Object.hasOwn(attrs, name)) continue
+    attrs[name] = decodeHtmlEntities(match[2] ?? match[3] ?? match[4] ?? "")
+  }
+  return attrs
+}

package/html.ts

@@ -0,0 +1,48 @@
+import { escapeHtml } from "./util.ts"
+
+const HTML_FRAGMENT = Symbol("PathMX.Html")
+
+type HtmlFragment = Readonly<{
+  [HTML_FRAGMENT]: string
+  toString(): string
+}>
+
+/** HTML returned by plugins: an existing string or a safely composed fragment. */
+export type Html = string | HtmlFragment
+
+type HtmlValue = Html | number | boolean | null | undefined | readonly HtmlValue[]
+
+function fragment(value: string): HtmlFragment {
+  return Object.freeze({
+    [HTML_FRAGMENT]: value,
+    toString: () => value,
+  })
+}
+
+function isFragment(value: HtmlValue): value is HtmlFragment {
+  return typeof value === "object" && value !== null && HTML_FRAGMENT in value
+}
+
+function interpolate(value: HtmlValue): string {
+  if (value == null || typeof value === "boolean") return ""
+  if (Array.isArray(value)) return value.map(interpolate).join("")
+  if (isFragment(value)) return value[HTML_FRAGMENT]
+  return escapeHtml(String(value)).replace(/'/g, "&#39;")
+}
+
+/** Compose trusted markup while escaping every ordinary interpolated value. */
+export function html(
+  strings: TemplateStringsArray,
+  ...values: readonly HtmlValue[]
+): HtmlFragment {
+  let output = strings[0] ?? ""
+  for (let index = 0; index < values.length; index++) {
+    output += interpolate(values[index]) + (strings[index + 1] ?? "")
+  }
+  return fragment(output)
+}
+
+/** Normalize plugin HTML at the private rendering boundary. */
+export function stringifyHtml(value: Html): string {
+  return typeof value === "string" ? value : value[HTML_FRAGMENT]
+}

package/icons/LICENSE

@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/icons/lucide.ts

@@ -0,0 +1,54 @@
+/** Generated by scripts/generate-lucide-icons.ts from @lucide/icons v1.34.0. */
+export const bugIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-bug" aria-hidden="true" focusable="false"><path d="M12 20v-9"></path><path d="M14 7a4 4 0 0 1 4 4v3a6 6 0 0 1-12 0v-3a4 4 0 0 1 4-4z"></path><path d="M14.12 3.88 16 2"></path><path d="M21 21a4 4 0 0 0-3.81-4"></path><path d="M21 5a4 4 0 0 1-3.55 3.97"></path><path d="M22 13h-4"></path><path d="M3 21a4 4 0 0 1 3.81-4"></path><path d="M3 5a4 4 0 0 0 3.55 3.97"></path><path d="M6 13H2"></path><path d="m8 2 1.88 1.88"></path><path d="M9 7.13V6a3 3 0 1 1 6 0v1.13"></path></svg>'
+
+export const checkIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-check" aria-hidden="true" focusable="false"><path d="M20 6 9 17l-5-5"></path></svg>'
+
+export const chevronRightIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-right" aria-hidden="true" focusable="false"><path d="m9 18 6-6-6-6"></path></svg>'
+
+export const circleCheckBigIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-circle-check-big lucide-check-circle" aria-hidden="true" focusable="false"><path d="M21.801 10A10 10 0 1 1 17 3.335"></path><path d="m9 11 3 3L22 4"></path></svg>'
+
+export const circleQuestionIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-circle-question-mark lucide-help-circle lucide-circle-help" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="10"></circle><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"></path><path d="M12 17h.01"></path></svg>'
+
+export const clipboardListIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-clipboard-list" aria-hidden="true" focusable="false"><rect width="8" height="4" x="8" y="2" rx="1" ry="1"></rect><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"></path><path d="M12 11h4"></path><path d="M12 16h4"></path><path d="M8 11h.01"></path><path d="M8 16h.01"></path></svg>'
+
+export const copyIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy" aria-hidden="true" focusable="false"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg>'
+
+export const flameIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-flame" aria-hidden="true" focusable="false"><path d="M12 3q1 4 4 6.5t3 5.5a1 1 0 0 1-14 0 5 5 0 0 1 1-3 1 1 0 0 0 5 0c0-2-1.5-3-1.5-5q0-2 2.5-4"></path></svg>'
+
+export const infoIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-info" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="10"></circle><path d="M12 16v-4"></path><path d="M12 8h.01"></path></svg>'
+
+export const listIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-list" aria-hidden="true" focusable="false"><path d="M3 5h.01"></path><path d="M3 12h.01"></path><path d="M3 19h.01"></path><path d="M8 5h13"></path><path d="M8 12h13"></path><path d="M8 19h13"></path></svg>'
+
+export const listTodoIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-list-todo" aria-hidden="true" focusable="false"><path d="M13 5h8"></path><path d="M13 12h8"></path><path d="M13 19h8"></path><path d="m3 17 2 2 4-4"></path><rect x="3" y="4" width="6" height="6" rx="1"></rect></svg>'
+
+export const moonIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-moon" aria-hidden="true" focusable="false"><path d="M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401"></path></svg>'
+
+export const pencilIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-pencil" aria-hidden="true" focusable="false"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"></path><path d="m15 5 4 4"></path></svg>'
+
+export const quoteIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-quote" aria-hidden="true" focusable="false"><path d="M16 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1v2a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z"></path><path d="M5 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1v2a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z"></path></svg>'
+
+export const sunIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-sun" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="4"></circle><path d="M12 2v2"></path><path d="M12 20v2"></path><path d="m4.93 4.93 1.41 1.41"></path><path d="m17.66 17.66 1.41 1.41"></path><path d="M2 12h2"></path><path d="M20 12h2"></path><path d="m6.34 17.66-1.41 1.41"></path><path d="m19.07 4.93-1.41 1.41"></path></svg>'
+
+export const triangleAlertIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-triangle-alert lucide-alert-triangle" aria-hidden="true" focusable="false"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"></path><path d="M12 9v4"></path><path d="M12 17h.01"></path></svg>'
+
+export const xIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-x" aria-hidden="true" focusable="false"><path d="M18 6 6 18"></path><path d="m6 6 12 12"></path></svg>'
+
+export const zapIconSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-zap" aria-hidden="true" focusable="false"><path d="M15.914 4a1.5 1.5 0 00-2.474-1.561l-9 9A1.5 1.5 0 005.5 14h4.002a.5.5 0 01.471.666L8.086 20a1.5 1.5 0 002.475 1.56l9-9A1.5 1.5 0 0018.5 10h-3.997a.5.5 0 01-.472-.667z"></path></svg>'

package/index.ts

@@ -0,0 +1,75 @@
+import { join } from "node:path"
+import { createApp, type CreateAppOptions } from "./host/create.ts"
+import { bunEnvironment } from "./environments/bun.ts"
+import { discoverRepositoryPlugins } from "./environments/bun-plugins.ts"
+import { Log, parseLogLevel } from "./log.ts"
+import { defaultPlugins } from "./plugins/index.ts"
+import {
+  expandPluginContributions,
+  instantiatePlugin,
+  type PluginContribution,
+} from "./plugins/preset.ts"
+
+export * from "./core.ts"
+export * from "./environments/bun.ts"
+
+type PathMXOptions = Omit<CreateAppOptions, "root" | "environment"> & {
+  root?: string
+  environment?: CreateAppOptions["environment"]
+}
+
+function composeRepositoryPlugins(
+  configured: readonly PluginContribution[],
+  discovered: readonly PluginContribution[],
+  allowDefaultReplacement: boolean,
+) {
+  if (!allowDefaultReplacement) return [...configured, ...discovered]
+
+  const plugins = expandPluginContributions(configured).map(instantiatePlugin)
+  const replacements = new Map(
+    plugins.map((plugin, index) => [plugin.id, index]),
+  )
+  const repositoryIds = new Set<string>()
+  for (const plugin of expandPluginContributions(discovered).map(
+    instantiatePlugin,
+  )) {
+    if (repositoryIds.has(plugin.id)) {
+      throw new Error(`Duplicate repository plugin id: ${plugin.id}`)
+    }
+    repositoryIds.add(plugin.id)
+    const index = replacements.get(plugin.id)
+    if (index === undefined) plugins.push(plugin)
+    else plugins[index] = plugin
+  }
+  return plugins
+}
+
+export async function PathMX(
+  rootOrOptions: string | PathMXOptions = {},
+  options: PathMXOptions = {},
+) {
+  const merged =
+    typeof rootOrOptions === "string"
+      ? { ...options, root: rootOrOptions }
+      : { ...rootOrOptions, ...options }
+  const root = merged.root ?? join(process.cwd(), "paths")
+  const environment = merged.environment ?? bunEnvironment
+  const log =
+    merged.log ?? new Log({ level: parseLogLevel(process.env.PATHMX_LOG) })
+  const discoveredPlugins =
+    environment === bunEnvironment
+      ? await discoverRepositoryPlugins(root, log)
+      : []
+  const configuredPlugins = merged.plugins ?? defaultPlugins
+  return createApp({
+    ...merged,
+    root,
+    environment,
+    plugins: composeRepositoryPlugins(
+      configuredPlugins,
+      discoveredPlugins,
+      merged.plugins === undefined,
+    ),
+    log,
+  })
+}

package/invalidation.ts

@@ -0,0 +1,85 @@
+export type RouteInvalidationTarget =
+  | { type: "route"; route: string; actors?: string[] }
+  | { type: "actor"; actors: string[] }
+
+export type RouteInvalidation = {
+  targets: RouteInvalidationTarget[]
+}
+
+function canonicalRoute(route: string) {
+  if (!route) return "/"
+  const rooted = route.startsWith("/") ? route : "/" + route
+  return rooted.length > 1 ? rooted.replace(/\/+$/, "") : rooted
+}
+
+/** Collect route invalidations, collapsing Actor-specific targets into all-Actor targets. */
+export class RouteInvalidations {
+  private routes = new Map<string, Set<string> | undefined>()
+  private actors = new Set<string>()
+
+  add(route: string, actor?: string) {
+    const key = canonicalRoute(route)
+    if (this.routes.has(key) && this.routes.get(key) === undefined) return
+    if (!actor) {
+      this.routes.set(key, undefined)
+      return
+    }
+    const actors = this.routes.get(key) ?? new Set<string>()
+    actors.add(actor)
+    this.routes.set(key, actors)
+  }
+
+  addActors(route: string, actors: Iterable<string>) {
+    for (const actor of actors) this.add(route, actor)
+  }
+
+  addActorTargets(actors: Iterable<string>) {
+    for (const actor of actors) this.actors.add(actor)
+  }
+
+  event(): RouteInvalidation {
+    return {
+      targets: [
+        ...[...this.routes]
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([route, actors]) => ({
+            type: "route" as const,
+            route,
+            ...(actors ? { actors: [...actors].sort() } : {}),
+          })),
+        ...(this.actors.size
+          ? [
+              {
+                type: "actor" as const,
+                actors: [...this.actors].sort(),
+              },
+            ]
+          : []),
+      ],
+    }
+  }
+}
+
+export function cachedRouteTargets(pages: Iterable<{ route: string }>) {
+  return [...pages].map((page) => ({
+    type: "route" as const,
+    route: page.route,
+  }))
+}
+
+export function matchesInvalidation(
+  event: RouteInvalidation,
+  route: string,
+  actor?: string,
+) {
+  const key = canonicalRoute(route)
+  return event.targets.some((target) => {
+    if (target.type === "actor") {
+      return actor != null && target.actors.includes(actor)
+    }
+    return (
+      target.route === key &&
+      (!target.actors || (actor != null && target.actors.includes(actor)))
+    )
+  })
+}

package/log.ts

@@ -0,0 +1,84 @@
+export type LogLevel = "debug" | "info" | "warn" | "error"
+
+export type LogRecord = {
+  time: number
+  level: LogLevel
+  message: string
+  context?: Record<string, unknown>
+}
+
+export type LogSink = (record: LogRecord) => void
+
+const RANK: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+}
+
+export function parseLogLevel(value: string | undefined): LogLevel {
+  if (
+    value === "debug" ||
+    value === "info" ||
+    value === "warn" ||
+    value === "error"
+  )
+    return value
+  return "info"
+}
+
+export function formatLog(record: LogRecord) {
+  const time = new Date(record.time).toISOString()
+  const extras = record.context
+    ? Object.entries(record.context)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join(" ")
+    : ""
+  return extras
+    ? `${time} ${record.level} ${record.message} ${extras}`
+    : `${time} ${record.level} ${record.message}`
+}
+
+export function consoleSink(record: LogRecord) {
+  const line = formatLog(record)
+  if (record.level === "error") console.error(line)
+  else if (record.level === "warn") console.warn(line)
+  else console.log(line)
+}
+
+export class Log {
+  level: LogLevel
+  sink: LogSink
+  records: LogRecord[] = []
+  limit: number
+
+  constructor(options?: { level?: LogLevel; sink?: LogSink; limit?: number }) {
+    this.level = options?.level ?? "info"
+    this.sink = options?.sink ?? consoleSink
+    this.limit = options?.limit ?? 1000
+  }
+
+  write(level: LogLevel, message: string, context?: Record<string, unknown>) {
+    const record: LogRecord = { time: Date.now(), level, message, context }
+    this.records.push(record)
+    if (this.records.length > this.limit) this.records.shift()
+    if (RANK[level] >= RANK[this.level]) this.sink(record)
+  }
+
+  debug(message: string, context?: Record<string, unknown>) {
+    this.write("debug", message, context)
+  }
+
+  info(message: string, context?: Record<string, unknown>) {
+    this.write("info", message, context)
+  }
+
+  warn(message: string, context?: Record<string, unknown>) {
+    this.write("warn", message, context)
+  }
+
+  error(message: string, context?: Record<string, unknown>) {
+    this.write("error", message, context)
+  }
+}