@pathmx/core 0.5.0 → 0.5.2

package/document.ts

@@ -19,9 +19,12 @@ export function documentAssetRank(asset: DocumentAsset) {
 export function documentAssetKey(asset: DocumentAsset) {
   if (asset.type === "style") return `style:${asset.text}`
   if (asset.type === "script") {
-    if ("name" in asset && asset.name) return `script:name:${asset.name}`
-    if ("source" in asset) return `script:source:${asset.source}`
-    return "href" in asset ? `script:${asset.href}` : `script:${asset.text}`
+    const mode = asset.module ? "module" : "classic"
+    if ("name" in asset) return `script:name:${asset.name}:${mode}`
+    if ("source" in asset) return `script:source:${asset.source}:${mode}`
+    return "href" in asset
+      ? `script:href:${asset.href}:${mode}`
+      : `script:inline:${asset.text}:${mode}`
   }
   if (asset.type === "title") return "title"
   if (asset.type === "preload") {
@@ -31,8 +34,10 @@ export function documentAssetKey(asset: DocumentAsset) {
     const { charset, name, property } = asset.attrs
     return `meta:${charset != null ? "charset" : (name ?? property ?? JSON.stringify(asset.attrs))}:${asset.attrs.media ?? ""}`
   }
-  if ("name" in asset && asset.name) return `stylesheet:name:${asset.name}`
-  return `stylesheet:${"href" in asset ? asset.href : ""}`
+  const media = asset.media ?? "all"
+  if ("name" in asset) return `stylesheet:name:${asset.name}:${media}`
+  if ("source" in asset) return `stylesheet:source:${asset.source}:${media}`
+  return `stylesheet:href:${"href" in asset ? asset.href : ""}:${media}`
 }
 
 function pushUniqueAsset(assets: DocumentAsset[], asset: DocumentAsset) {
@@ -81,6 +86,11 @@ export function renderDocumentAssets(assets: readonly DocumentAsset[]) {
         return `<link rel="preload" href="${escapeHtml(asset.href)}" as="${escapeHtml(asset.as)}"${contentType}${crossorigin}>`
       }
       if (asset.type === "stylesheet") {
+        if ("source" in asset) {
+          throw new Error(
+            `Unresolved authored stylesheet asset: ${asset.source}`,
+          )
+        }
         const href = "href" in asset ? asset.href : ""
         const media = asset.media ? ` media="${escapeHtml(asset.media)}"` : ""
         return `<link rel="stylesheet" href="${escapeHtml(href)}"${media}>`

package/environments/bun.ts

@@ -15,6 +15,7 @@ import type {
   HtmlRewrite,
   PathMXEnvironment,
 } from "../environment.ts"
+import { isAuthoredStoragePath } from "../storage-path.ts"
 
 export { publishToDirectory, writePublication } from "./bun-publish.ts"
 
@@ -201,9 +202,10 @@ export const bunEnvironment: PathMXEnvironment = {
     stringify: (value) => YAML.stringify(value, null, 2),
   },
   storage: {
-    list: (root) => [
-      ...new Bun.Glob("**/*").scanSync({ cwd: root, onlyFiles: true }),
-    ],
+    list: (root) =>
+      [
+        ...new Bun.Glob("**/*").scanSync({ cwd: root, onlyFiles: true }),
+      ].filter(isAuthoredStoragePath),
     readText: (path) => Bun.file(path).text(),
     readBlob: (path) => Bun.file(path),
     writeText: async (path, content) => {

package/host/authored-assets.ts

@@ -0,0 +1,98 @@
+import { canonicalPath } from "../canonical.ts"
+import type { PathMXEnvironment } from "../environment.ts"
+import type { Repository } from "../repository.ts"
+import { resolveRoute } from "../server/router.ts"
+import type { AssetStore } from "../assets.ts"
+
+type Resolution = Readonly<{
+  generation: number
+  href: Promise<string>
+}>
+
+export class AuthoredAssetError extends Error {
+  constructor(
+    readonly sourcePath: string,
+    message: string,
+  ) {
+    super(`Authored asset ${sourcePath}: ${message}`)
+    this.name = "AuthoredAssetError"
+  }
+}
+
+/** Resolve repository assets once per source revision without pinning old Blobs. */
+export class AuthoredAssets {
+  private generations = new Map<string, number>()
+  private resolutions = new Map<string, Map<string, Resolution>>()
+
+  constructor(
+    private repo: Repository,
+    private environment: PathMXEnvironment,
+    private store: AssetStore,
+  ) {}
+
+  async resolve(source: string, contentType: string) {
+    const sourcePath = canonicalPath(source)
+
+    while (true) {
+      const generation = this.generations.get(sourcePath) ?? 0
+      const byContentType = this.resolutions.get(sourcePath) ?? new Map()
+      let resolution = byContentType.get(contentType)
+      if (!resolution || resolution.generation !== generation) {
+        resolution = {
+          generation,
+          href: this.publish(sourcePath, contentType),
+        }
+        byContentType.set(contentType, resolution)
+        this.resolutions.set(sourcePath, byContentType)
+      }
+
+      let href: string
+      try {
+        href = await resolution.href
+      } catch (error) {
+        if (byContentType.get(contentType) === resolution) {
+          byContentType.delete(contentType)
+          if (!byContentType.size) this.resolutions.delete(sourcePath)
+        }
+        throw error
+      }
+
+      if ((this.generations.get(sourcePath) ?? 0) !== generation) continue
+      if (this.store.get(href)) return href
+
+      if (byContentType.get(contentType) === resolution) {
+        byContentType.delete(contentType)
+        if (!byContentType.size) this.resolutions.delete(sourcePath)
+      }
+    }
+  }
+
+  invalidate(paths: Iterable<string>) {
+    for (const path of paths) {
+      const sourcePath = canonicalPath(this.repo.graphPath(path))
+      this.generations.set(
+        sourcePath,
+        (this.generations.get(sourcePath) ?? 0) + 1,
+      )
+      this.resolutions.delete(sourcePath)
+    }
+  }
+
+  private async publish(sourcePath: string, contentType: string) {
+    const storagePath = this.repo.storagePath(sourcePath)
+    if (!storagePath || !(await this.repo.isFile(sourcePath))) {
+      throw new AuthoredAssetError(sourcePath, "source file was not found.")
+    }
+
+    const blob = await this.environment.storage.readBlob(storagePath)
+    const href = await this.store.publishAuthored(sourcePath, blob, contentType)
+    if ((await this.repo.isFile(href)) || resolveRoute(this.repo, href)) {
+      this.store.delete(href)
+      throw new AuthoredAssetError(
+        sourcePath,
+        `delivery URL conflicts with an authored route: ${href}`,
+      )
+    }
+    return href
+  }
+}

package/host/engine.ts

@@ -54,10 +54,11 @@ import {
   documentAssetRank,
   renderDocumentAssets,
 } from "../document.ts"
-import { GeneratedAssets } from "../assets.ts"
+import { AssetStore } from "../assets.ts"
 import { PluginHost } from "./plugin-host.ts"
 import { PageCompiler } from "./compiler.ts"
 import { SourceSynchronizer } from "./source-sync.ts"
+import { AuthoredAssets } from "./authored-assets.ts"
 import { PluginDatabases } from "../database.ts"
 import { projectDirectory } from "../project.ts"
 import { browserBundleAssets } from "../browser-bundle.ts"
@@ -88,8 +89,8 @@ export class Engine {
   perf = new Perf()
   log: Log
   private bundles = new Map<string, Promise<BundledAsset[]>>()
-  private assetRevisions = new Map<string, number>()
-  private generatedAssets: GeneratedAssets
+  private assetStore: AssetStore
+  private authoredAssets: AuthoredAssets
   private actorIndex: KnownActorIndex
   private accessPolicy: SourceAccessPolicy
   private authorityErrors = new Map<string, string>()
@@ -113,10 +114,11 @@ export class Engine {
     this.repo = repo
     this.environment = environment
     this.runtime = createRuntimeProfile(runtime)
-    this.generatedAssets =
+    this.assetStore =
       this.runtime.target === "static"
-        ? new GeneratedAssets(Number.POSITIVE_INFINITY)
-        : new GeneratedAssets()
+        ? new AssetStore(Number.POSITIVE_INFINITY)
+        : new AssetStore()
+    this.authoredAssets = new AuthoredAssets(repo, environment, this.assetStore)
     this.graph = new Graph(repo)
     this.actorIndex = actors
     this.profiles = profiles
@@ -212,30 +214,33 @@ export class Engine {
     const ctx = { page, addAsset, addBrowserBundle }
     await this.pluginHost.documentAssets(ctx, this)
     addAsset(...(page?.assets ?? []))
-    return assets
-      .map((asset) => this.resolveDocumentAsset(asset))
-      .sort((a, b) => documentAssetRank(a) - documentAssetRank(b))
+    const resolved = await Promise.all(
+      assets.map((asset) => this.resolveDocumentAsset(asset)),
+    )
+    return resolved.sort((a, b) => documentAssetRank(a) - documentAssetRank(b))
   }
 
   servedAsset(pathname: string) {
-    return this.generatedAssets.get(pathname)
+    return this.assetStore.get(pathname)
   }
 
-  /** @internal Enumerate retained generated artifacts during static publication. */
-  generatedAssetEntries() {
-    return this.generatedAssets.entries()
+  /** @internal Enumerate retained artifacts during static publication. */
+  servedAssetEntries() {
+    return this.assetStore.entries()
   }
 
   /** Publish an immutable, content-hashed binary asset under `/.pmx/`. */
   async publishAsset(name: string, blob: Blob, contentType = blob.type) {
-    return this.generatedAssets.publishBlob(name, blob, contentType)
+    return this.assetStore.publishBlob(name, blob, contentType)
   }
 
   onSync(listener: (event: RouteInvalidation) => void) {
     return this.sourceSync.onSync(listener)
   }
 
-  private resolveDocumentAsset(asset: DocumentAsset): DocumentAsset {
+  private async resolveDocumentAsset(
+    asset: DocumentAsset,
+  ): Promise<DocumentAsset> {
     if (asset.type === "stylesheet" && "name" in asset) {
       const href = this.storeNamed(
         asset.name,
@@ -248,6 +253,17 @@ export class Engine {
         ...(asset.media ? { media: asset.media } : {}),
       }
     }
+    if (asset.type === "stylesheet" && "source" in asset) {
+      const href = await this.authoredAssets.resolve(
+        asset.source,
+        "text/css; charset=utf-8",
+      )
+      return {
+        type: "stylesheet",
+        href,
+        ...(asset.media ? { media: asset.media } : {}),
+      }
+    }
     if (asset.type === "script" && "name" in asset) {
       const href = this.storeNamed(
         asset.name,
@@ -257,25 +273,21 @@ export class Engine {
       return { type: "script", href, module: asset.module }
     }
     if (asset.type === "script" && "source" in asset) {
-      const revision = this.assetRevisions.get(asset.source)
-      const href = revision ? `${asset.source}?pmx=${revision}` : asset.source
+      const href = await this.authoredAssets.resolve(
+        asset.source,
+        "text/javascript; charset=utf-8",
+      )
       return { type: "script", href, module: asset.module }
     }
     return asset
   }
 
-  bumpAssetRevisions(paths: Iterable<string>) {
-    for (const path of paths) {
-      const graphPath = this.repo.graphPath(path)
-      this.assetRevisions.set(
-        graphPath,
-        (this.assetRevisions.get(graphPath) ?? 0) + 1,
-      )
-    }
+  invalidateAuthoredAssets(paths: Iterable<string>) {
+    this.authoredAssets.invalidate(paths)
   }
 
   private storeNamed(name: string, text: string, contentType: string) {
-    return this.generatedAssets.publishText(name, text, contentType)
+    return this.assetStore.publishText(name, text, contentType)
   }
 
   async documentHead(page?: CompiledPage) {
@@ -422,6 +434,13 @@ export class Engine {
       "index.source",
       () => {
         this.forgetNode(source.path)
+        if (Object.hasOwn(source.data, "id")) {
+          this.log.warn("source.id.ignored", {
+            source: source.path,
+            message:
+              'Source frontmatter "id" is ignored; Source ids are derived from file paths.',
+          })
+        }
         this.compiler.indexSource(source)
         this.authorityErrors.delete(source.id)
         const capture = (error: unknown) => {

package/host/shell.html

@@ -11,5 +11,6 @@
     >
       {{ content }}
     </div>
+    <div data-pmx-augmentations></div>
   </body>
 </html>

package/host/source-sync.ts

@@ -229,7 +229,7 @@ export class SourceSynchronizer {
 
   invalidateAssets(paths: Iterable<string>) {
     const changed = [...paths]
-    this.engine.bumpAssetRevisions(changed)
+    this.engine.invalidateAuthoredAssets(changed)
     const invalidations = new RouteInvalidations()
     for (const path of changed) {
       const graphPath = this.engine.repo.graphPath(path)

package/ops/href.ts

@@ -23,16 +23,6 @@ export function isRelativeHref(pathname: string) {
   )
 }
 
-export function authoredId(source: Source) {
-  const id = source.data.id
-  return typeof id === "string" && id.trim() ? id.trim() : undefined
-}
-
-export function isAuthoredIdHref(pathname: string, source: Source) {
-  const id = authoredId(source)
-  return Boolean(id && (pathname === id || pathname === `/${id}`))
-}
-
 export function relativeHref(
   fromPath: string,
   targetPath: string,
@@ -75,7 +65,6 @@ export function retargetHref(
 ): string | undefined {
   const { pathname, query, fragment } = splitHref(href)
   if (!pathname) return
-  if (isAuthoredIdHref(pathname, oldSource)) return
 
   const explicitMd = pathname.endsWith(".md")
   const target = explicitMd ? newSource.path : publicPath(newSource)

package/ops/move-source.ts

@@ -3,7 +3,6 @@ import { posixPath } from "../path.ts"
 import { isIndexSource, publicPath } from "../server/router.ts"
 import { createSource, rewriteLinks, type Source } from "../source/index.ts"
 import {
-  authoredId,
   isRelativeHref,
   rebaseRelativeHref,
   retargetHref,
@@ -104,9 +103,12 @@ export async function moveSource(
       `Moving index source ${source.path} changes the directory route ${publicPath(source)}`,
     )
   }
-  if (!authoredId(source) && source.id !== preview.id) {
+  if (
+    !isIndexSource(source) &&
+    publicPath(source) !== publicPath(preview)
+  ) {
     plan.warnings.push(
-      `Moving ${source.path} changes its public URL from ${source.id} to ${preview.id}`,
+      `Moving ${source.path} changes its public URL from ${publicPath(source)} to ${publicPath(preview)}`,
     )
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pathmx/core",
   "description": "A minimal, plugin-first framework for Paths and learning applications.",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",

package/plugins/runtime/document.ts

@@ -42,6 +42,15 @@ export class PathMXReloadRequiredError extends PathMXDocumentError {
   }
 }
 
+const AUGMENTATIONS_SELECTOR = "body > [data-pmx-augmentations]"
+
+function augmentationLayer(target: Document) {
+  const layers = target.querySelectorAll(AUGMENTATIONS_SELECTOR)
+  return layers.length === 1 && layers[0] instanceof HTMLElement
+    ? layers[0]
+    : undefined
+}
+
 function assetUrl(element: Element, attribute: "href" | "src") {
   try {
     return new URL(element.getAttribute(attribute) || "", location.href)
@@ -55,21 +64,23 @@ function stylesheetKey(link: Element) {
   if (!href) return link.getAttribute("href") || ""
   href.search = ""
   if (isHashedAsset(href.pathname)) {
-    return href.pathname.replace(/-[0-9a-f]{16}(?=\.[^/]+$)/, "")
+    return href.pathname.replace(HASHED_ASSET, "")
   }
   return href.pathname
 }
 
 function isHashedAsset(pathname: string) {
-  return pathname.startsWith(publicationPath("/.pmx/"))
+  return HASHED_ASSET.test(pathname)
 }
 
+const HASHED_ASSET = /-[0-9a-f]{16}(?=\.[^/]+$)/
+
 function scriptKey(script: Element) {
   const src = assetUrl(script, "src")
   if (!src) return script.getAttribute("src") || ""
   src.search = ""
   if (isHashedAsset(src.pathname)) {
-    return src.pathname.replace(/-[0-9a-f]{16}(?=\.[^/]+$)/, "")
+    return src.pathname.replace(HASHED_ASSET, "")
   }
   return src.href
 }
@@ -157,7 +168,7 @@ function reconcileStylesheets(
       current.append(incomingLink.cloneNode(true))
       continue
     }
-    if (isHashedAsset(key)) {
+    if (isHashedAsset(assetUrl(incomingLink, "href")?.pathname ?? "")) {
       if (currentLink.getAttribute("href") === nextHref) continue
       const added = incomingLink.cloneNode(true) as HTMLLinkElement
       added.addEventListener("load", () => currentLink.remove(), { once: true })
@@ -415,6 +426,11 @@ export async function readPathMXDocument(
   if (views.length !== 1 || !(views[0] instanceof HTMLElement)) {
     throw new PathMXDocumentError("The response has no canonical PathMX view.")
   }
+  if (!augmentationLayer(incoming)) {
+    throw new PathMXDocumentError(
+      "The response has no canonical PathMX augmentation layer.",
+    )
+  }
   return {
     document: incoming,
     requestedUrl,
@@ -446,6 +462,9 @@ export async function reconcilePathMXDocument(
     viewTransitionTypes?: readonly string[]
   },
 ) {
+  if (!augmentationLayer(document)) {
+    throw new PathMXReloadRequiredError("The PathMX document shell changed.")
+  }
   const viewTransitionTypes = options.viewTransitionTypes ?? []
   const apply = () => {
     const canonicalView = window.__pmxCanonicalView ?? currentView()

package/plugins/runtime/runtime.css

@@ -0,0 +1,6 @@
+body > [data-pmx-augmentations] {
+  position: fixed;
+  z-index: var(--pmx-augmentations-z-index, 1000);
+  inset: 0;
+  pointer-events: none;
+}

package/plugins/runtime/start.ts

@@ -1,3 +1,4 @@
+import "./runtime.css"
 import {
   fetchPathMXDocument,
   PathMXReloadRequiredError,

package/plugins/styles.ts

@@ -1,15 +1,15 @@
 import { cachedRouteTargets } from "../invalidation.ts"
 import { parseLinks, type Source, type SourceLink } from "../source/index.ts"
-import type {
-  DependencyContext,
-  DocumentAsset,
-  DocumentStylesheet,
-  Plugin,
-} from "./types.ts"
+import type { DependencyContext, Plugin } from "./types.ts"
 import { directiveDefinition } from "./directive-definitions.ts"
 
 const MEDIA = new Set(["print", "screen"])
 const EXTERNAL = /^[a-z][a-z\d+.-]*:/i
+type AuthoredStylesheet = Readonly<{
+  type: "stylesheet"
+  source: string
+  media?: string
+}>
 
 function resolveTarget(source: Source, target: string) {
   return target.startsWith("/")
@@ -24,7 +24,7 @@ function styleLinks(source: Source, links: readonly SourceLink[]) {
 function resolveStylesheet(
   source: Source,
   link: SourceLink,
-): DocumentStylesheet | undefined {
+): AuthoredStylesheet | undefined {
   if (link.directive?.name !== "styles") return
   const raw = link.href.split("#")[0]?.split("?")[0] ?? ""
   if (
@@ -34,28 +34,31 @@ function resolveStylesheet(
     raw.startsWith("~/")
   )
     return
-  const href = resolveTarget(source, raw)
-  if (!href.endsWith(".css")) return
+  const sourcePath = resolveTarget(source, raw)
+  if (!sourcePath.endsWith(".css")) return
   const media = link.directive.qualifiers.find((item) => MEDIA.has(item))
-  return { type: "stylesheet", href, ...(media ? { media } : {}) }
+  return {
+    type: "stylesheet",
+    source: sourcePath,
+    ...(media ? { media } : {}),
+  }
 }
 
-function stylesheetHref(asset: DocumentAsset | DocumentStylesheet) {
-  return asset.type === "stylesheet" && "href" in asset ? asset.href : undefined
+function stylesheetKey(asset: AuthoredStylesheet) {
+  return `${asset.source}\0${asset.media ?? ""}`
 }
 
-function pushUnique(assets: DocumentAsset[], asset: DocumentStylesheet) {
-  const href = stylesheetHref(asset)
-  if (href && assets.some((item) => stylesheetHref(item) === href)) return
+function pushUnique(assets: AuthoredStylesheet[], asset: AuthoredStylesheet) {
+  const key = stylesheetKey(asset)
+  if (assets.some((item) => stylesheetKey(item) === key)) return
   assets.push(asset)
 }
 
 function addStylesheetDependency(
   dependencies: DependencyContext,
-  asset: DocumentStylesheet,
+  asset: AuthoredStylesheet,
 ) {
-  const href = stylesheetHref(asset)
-  if (href) dependencies.depend({ type: "source", path: href })
+  dependencies.depend({ type: "source", path: asset.source })
 }
 
 function sourceStyleLinks(source: Source) {
@@ -65,7 +68,7 @@ function sourceStyleLinks(source: Source) {
 }
 
 function globalStylesheets(source: Source, links: readonly SourceLink[]) {
-  const assets: DocumentStylesheet[] = []
+  const assets: AuthoredStylesheet[] = []
   for (const link of styleLinks(source, links)) {
     if (!link.directive?.qualifiers.includes("global")) continue
     const asset = resolveStylesheet(source, link)
@@ -74,10 +77,8 @@ function globalStylesheets(source: Source, links: readonly SourceLink[]) {
   return assets
 }
 
-function stylesheetSignature(assets: readonly DocumentStylesheet[]) {
-  return assets
-    .map((asset) => `${stylesheetHref(asset) ?? ""}\0${asset.media ?? ""}`)
-    .join("\n")
+function stylesheetSignature(assets: readonly AuthoredStylesheet[]) {
+  return assets.map(stylesheetKey).join("\n")
 }
 
 function authoredGlobalSignature(source?: Source) {
@@ -87,7 +88,7 @@ function authoredGlobalSignature(source?: Source) {
 }
 
 export function StylesPlugin(): Plugin {
-  const global = new Map<string, DocumentStylesheet[]>()
+  const global = new Map<string, AuthoredStylesheet[]>()
 
   return {
     id: "styles",

package/plugins/types.ts

@@ -47,6 +47,7 @@ export type CompileContext = DependencyContext & {
 
 export type DocumentStylesheet =
   | Readonly<{ type: "stylesheet"; href: string; media?: string }>
+  | Readonly<{ type: "stylesheet"; source: string; media?: string }>
   | Readonly<{
       type: "stylesheet"
       name: string

package/publish/build.ts

@@ -257,20 +257,30 @@ async function addAuthoredAssets(
     plan.addRoute({
       pathname: mounted,
       type: "asset",
-      representations: [fileRepresentation(artifact, type)],
+      representations: [
+        fileRepresentation(artifact, type, {
+          "cache-control": "public, max-age=0, must-revalidate",
+        }),
+      ],
     })
   }
 }
 
-function addGeneratedAssets(
+function addStoredAssets(
   app: Engine,
   plan: PublicationPlan,
   location: PublicationLocation,
 ) {
-  for (const [pathname, asset] of app.generatedAssetEntries()) {
+  for (const [pathname, asset] of app.servedAssetEntries()) {
+    if (
+      asset.type === "authored" &&
+      app.readAccess(anonymousPrincipal, asset.sourcePath) !== "public"
+    ) {
+      continue
+    }
     const mounted = location.pathname(pathname)
     if (plan.hasRoute(mounted)) {
-      throw new PublicationError(`Generated asset route collision: ${pathname}`)
+      throw new PublicationError(`Stored asset route collision: ${pathname}`)
     }
     const artifact = exactArtifact(mounted)
     plan.addArtifact({
@@ -384,7 +394,7 @@ export async function createPublication(
   await addPublishedRoutes(app, plan, location, published)
   await addSources(app, plan, store, location)
   await addAuthoredAssets(app, plan, location)
-  addGeneratedAssets(app, plan, location)
+  addStoredAssets(app, plan, location)
   await plan.materialize(store)
   const build = await plan.buildRoot(location.origin, location.basePath)
   const pages = addPageMap(plan, build, location)