@pathmx/core 0.5.0

package/plugins/image/index.ts

@@ -0,0 +1,68 @@
+import { parseDirectiveLabel } from "../../source/markdown/links.ts"
+import type { AppContext, Plugin } from "../types.ts"
+import stylesheet from "./theme.css" with { type: "text" }
+
+type ImageRole = "content" | "background"
+type ImageFit = "contain" | "cover"
+
+type ImageDirective = Readonly<{
+  role: ImageRole
+  fit: ImageFit
+}>
+
+const IMAGE_DIRECTIVES: Readonly<Record<string, ImageDirective>> =
+  Object.freeze({
+    fit: { role: "content", fit: "contain" },
+    fill: { role: "content", fit: "cover" },
+    background: { role: "background", fit: "cover" },
+    "background.fit": { role: "background", fit: "contain" },
+  })
+
+function imageDirective(alt: string) {
+  const parsed = parseDirectiveLabel(alt)
+  if (parsed.directive?.name.toLowerCase() !== "image") return
+  const qualifiers = parsed.directive.qualifiers
+    .map((qualifier) => qualifier.toLowerCase())
+    .join(".")
+  const directive = IMAGE_DIRECTIVES[qualifiers]
+  if (!directive) return
+  return { ...directive, alt: parsed.label ?? "" }
+}
+
+function rewriteImages(html: string, app: AppContext) {
+  if (!html.includes("<img")) return html
+  return app.html.rewrite(html, [
+    [
+      "img",
+      {
+        element(image) {
+          if (image.getAttribute("data-pmx-image")) return
+          const directive = imageDirective(image.getAttribute("alt") ?? "")
+          if (!directive) return
+          image.setAttribute("alt", directive.alt)
+          image.setAttribute("data-pmx-image", directive.role)
+          image.setAttribute("data-pmx-image-fit", directive.fit)
+        },
+      },
+    ],
+  ])
+}
+
+/** Compile portable Markdown image directives for any PathMX experience. */
+export function ImagePlugin(): Plugin {
+  return {
+    id: "image",
+    postcompile(html, _ctx, app) {
+      return rewriteImages(html, app)
+    },
+    page(html, ctx) {
+      if (!html.includes("data-pmx-image")) return html
+      ctx.addAsset({
+        type: "stylesheet",
+        name: "image.css",
+        text: stylesheet,
+      })
+      return html
+    },
+  }
+}

package/plugins/image/theme.css

@@ -0,0 +1,43 @@
+.pmx-document > [data-pmx-block]:has(> img[data-pmx-image="background"]),
+.pmx-document
+  > [data-pmx-block]:has(> p > img[data-pmx-image="background"]:only-child) {
+  position: relative;
+  isolation: isolate;
+}
+
+.pmx-document
+  > [data-pmx-block]
+  > :is(
+    img[data-pmx-image="background"],
+    p:has(> img[data-pmx-image="background"]:only-child)
+  ) {
+  position: absolute;
+  z-index: -1;
+  inset: 0;
+  max-inline-size: none;
+  margin: 0;
+  overflow: hidden;
+}
+
+.pmx-document
+  > [data-pmx-block]
+  > :is(
+    img[data-pmx-image="background"],
+    p:has(> img[data-pmx-image="background"]:only-child)
+  )
+  > img,
+.pmx-document > [data-pmx-block] > img[data-pmx-image="background"] {
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+  max-block-size: none;
+  border-radius: 0;
+}
+
+img[data-pmx-image-fit="contain"] {
+  object-fit: contain;
+}
+
+img[data-pmx-image-fit="cover"] {
+  object-fit: cover;
+}

package/plugins/include.ts

@@ -0,0 +1,119 @@
+import type { Source, SourceBlock } from "../source/index.ts"
+import { wrapBlockFlow } from "../document.ts"
+import { escapeHtml } from "../util.ts"
+import type { AppContext, DependencyContext, Plugin } from "./types.ts"
+
+const INCLUDE_SLOT = /<div data-pathmx-include="(\d+)"><\/div>/g
+
+function escapeRegex(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+function includeMarkup(href: string) {
+  const dest = escapeRegex(href)
+  return new RegExp(
+    `\\[@include(?:\\.[A-Za-z][\\w-]*)*(?:\\s+[^\\]]+)?\\]\\(\\s*(?:<${dest}>|${dest})\\)`,
+  )
+}
+
+function resolveTarget(source: Source, target: string) {
+  return target.startsWith("/")
+    ? target
+    : new URL(target, `file://${source.path}`).pathname
+}
+
+function includeLabel(resolved: string, anchor?: string) {
+  return anchor ? `${resolved}#${anchor}` : resolved
+}
+
+function includedSectionId(blockPath: string) {
+  return `include-${encodeURIComponent(blockPath)}`
+}
+
+function occupiesPageBlock(markdown: string, href: string, scope: string) {
+  if (scope !== "page" || href.includes("#")) return false
+  const value = markdown.trim()
+  const match = value.match(includeMarkup(href))
+  return match?.index === 0 && match[0] === value
+}
+
+async function compileIncludedBlock(
+  included: Source,
+  block: SourceBlock,
+  app: AppContext,
+  dependencies: DependencyContext,
+) {
+  return app.compile.block(included, block, dependencies, {
+    id: includedSectionId(block.path),
+  })
+}
+
+async function compileInclude(
+  source: Source,
+  href: string,
+  app: AppContext,
+  dependencies: DependencyContext,
+) {
+  const hash = href.indexOf("#")
+  const target = hash === -1 ? href : href.slice(0, hash)
+  const anchor = hash === -1 ? undefined : href.slice(hash + 1)
+  const resolved = resolveTarget(source, target)
+  dependencies.depend({ type: "source", path: resolved })
+  const included = app.sources.get(resolved)
+  if (!included) {
+    return `<p>[Broken Include: ${escapeHtml(includeLabel(resolved, anchor))}]</p>`
+  }
+  if (!app.access.canEmbed(source.id, included.id)) {
+    return `<p>[Unavailable Include: ${escapeHtml(includeLabel(resolved, anchor))}]</p>`
+  }
+  if (anchor === undefined) {
+    if (!included.blocks.length) {
+      return `<p>[Broken Include: ${escapeHtml(resolved)}]</p>`
+    }
+    const parts: string[] = []
+    for (const block of included.blocks) {
+      parts.push(await compileIncludedBlock(included, block, app, dependencies))
+    }
+    return parts.join("\n")
+  }
+  const block = included.blocks.find((item) => item.id === anchor)
+  if (!block) {
+    return `<p>[Broken Include: ${escapeHtml(`${resolved}#${anchor}`)}]</p>`
+  }
+  return compileIncludedBlock(included, block, app, dependencies)
+}
+
+export function IncludePlugin(): Plugin {
+  return {
+    id: "include",
+    async precompile(markdown, ctx, app) {
+      const includes = (ctx.block?.links ?? ctx.source.links).filter(
+        (link) => link.directive?.name === "include",
+      )
+      if (!includes.length) return markdown
+
+      let current = markdown
+      for (const link of includes) {
+        const compiled = await compileInclude(ctx.source, link.href, app, ctx)
+        const expandsBlockFlow =
+          includes.length === 1 &&
+          occupiesPageBlock(markdown, link.href, ctx.scope) &&
+          compiled.trimStart().startsWith("<section ")
+        ctx.slots.push(expandsBlockFlow ? wrapBlockFlow(compiled) : compiled)
+        current = current.replace(
+          includeMarkup(link.href),
+          `\n\n<div data-pathmx-include="${ctx.slots.length - 1}"></div>\n\n`,
+        )
+      }
+      return current
+    },
+
+    postcompile(html, ctx) {
+      if (!ctx.slots.length) return html
+      return html.replace(
+        INCLUDE_SLOT,
+        (_match, index) => ctx.slots[Number(index)] ?? "",
+      )
+    },
+  }
+}

package/plugins/index.ts

@@ -0,0 +1,91 @@
+import type { PluginFactory } from "./types.ts"
+import { CalloutPlugin } from "./callout/index.ts"
+import { DefinitionListPlugin } from "./definition-list.ts"
+import { IncludePlugin } from "./include.ts"
+import { CodeHighlightPlugin } from "./code-highlight/index.ts"
+import { MathPlugin } from "./math/index.ts"
+import { DatatypePlugin } from "./datatype/index.ts"
+import { StylesPlugin } from "./styles.ts"
+import { ScriptsPlugin } from "./scripts.ts"
+import { ComponentTemplatePlugin } from "./literate/index.ts"
+import { ActorPathPlugin } from "./actor-path.ts"
+import { ActorProfilePlugin } from "./actor-profile.ts"
+import { CanonicalLinkPlugin } from "./canonical-links.ts"
+import { SourcePreviewPlugin } from "./source-preview/index.ts"
+import { TableOfContentsPlugin } from "./toc/index.ts"
+import { ThemePlugin } from "./theme/index.ts"
+import { RuntimePlugin } from "./runtime/index.ts"
+import { LayoutPlugin } from "./layout.ts"
+import { NavigationPlugin } from "./navigation/index.ts"
+import { InputPlugin, createInputPlugin } from "./input/index.ts"
+import { AgentBrowsingPlugin } from "./agent-browsing.ts"
+import { QueryPlugin } from "./query/index.ts"
+import { EmbeddingPlugin } from "./embedding/index.ts"
+import { ImagePlugin } from "./image/index.ts"
+import { BlockLayoutPlugin } from "./block-layout/index.ts"
+
+export {
+  AgentBrowsingPlugin,
+  ActorPathPlugin,
+  ActorProfilePlugin,
+  BlockLayoutPlugin,
+  CanonicalLinkPlugin,
+  CalloutPlugin,
+  CodeHighlightPlugin,
+  ComponentTemplatePlugin,
+  DatatypePlugin,
+  DefinitionListPlugin,
+  EmbeddingPlugin,
+  IncludePlugin,
+  ImagePlugin,
+  InputPlugin,
+  createInputPlugin,
+  LayoutPlugin,
+  MathPlugin,
+  QueryPlugin,
+  NavigationPlugin,
+  RuntimePlugin,
+  ScriptsPlugin,
+  SourcePreviewPlugin,
+  StylesPlugin,
+  TableOfContentsPlugin,
+  ThemePlugin,
+}
+export type { InputAuthoring, InputAuthoringResult } from "./input/authoring.ts"
+export type { InputControl } from "./input/model.ts"
+export type {
+  CanonicalLinkPluginOptions,
+  ExternalWebLinks,
+} from "./canonical-links.ts"
+export type {
+  EmbeddingExternalLinks,
+  EmbeddingPluginOptions,
+} from "./embedding/index.ts"
+
+/** Standard PathMX experience layered over createApp's portable foundation. */
+export const defaultPlugins = Object.freeze([
+  CalloutPlugin,
+  QueryPlugin,
+  AgentBrowsingPlugin,
+  ThemePlugin,
+  DefinitionListPlugin,
+  IncludePlugin,
+  ImagePlugin,
+  BlockLayoutPlugin,
+  CodeHighlightPlugin,
+  MathPlugin,
+  DatatypePlugin,
+  StylesPlugin,
+  ScriptsPlugin,
+  TableOfContentsPlugin,
+  ComponentTemplatePlugin,
+  InputPlugin,
+  CanonicalLinkPlugin,
+  SourcePreviewPlugin,
+  LayoutPlugin,
+  NavigationPlugin,
+  EmbeddingPlugin,
+  ActorProfilePlugin,
+  ActorPathPlugin,
+  RuntimePlugin,
+] satisfies readonly PluginFactory[])

package/plugins/input/authoring.ts

@@ -0,0 +1,236 @@
+import {
+  formatSchemaIssues,
+  type StandardSchemaV1,
+} from "../../schema/standard.ts"
+import type { Source } from "../../source/index.ts"
+import { authoredViewComponentUses } from "../../view/syntax.ts"
+import type { ViewComponentUse } from "../types.ts"
+import { inputResponseConfig } from "./config.ts"
+import type { InputChoice, InputControl, InputText } from "./model.ts"
+
+export type InputAuthoringResult = Readonly<{
+  controls: readonly InputControl[]
+  completion?: Readonly<{ key: string }>
+  issues?: readonly string[]
+}>
+
+export type InputAuthoring = Readonly<{
+  inspect(source: Source): InputAuthoringResult | undefined
+}>
+
+type Props = Readonly<Record<string, string>>
+
+function propsSchema(
+  required: readonly string[],
+  optional: readonly string[] = [],
+): StandardSchemaV1<unknown, Props> {
+  const allowed = new Set([...required, ...optional])
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "pathmx",
+      validate(value) {
+        const props = value as Record<string, unknown>
+        const issues: StandardSchemaV1.Issue[] = []
+        for (const name of required) {
+          if (typeof props?.[name] !== "string" || !props[name]) {
+            issues.push({ message: "Required", path: [name] })
+          }
+        }
+        for (const name of Object.keys(props ?? {})) {
+          if (!allowed.has(name)) {
+            issues.push({ message: "Unknown prop", path: [name] })
+          }
+        }
+        return issues.length ? { issues } : { value: props as Props }
+      },
+    },
+  }
+}
+
+export const optionProps = propsSchema(
+  ["name", "value", "label"],
+  ["required", "min"],
+)
+export const textProps = propsSchema(
+  ["name", "label"],
+  ["placeholder", "required"],
+)
+export const submitProps = propsSchema(["label"])
+
+export function optionFrom(
+  use: ViewComponentUse,
+  type: InputChoice["type"],
+): InputChoice {
+  const min =
+    use.props.min == null || use.props.min === "" ? 0 : Number(use.props.min)
+  if (!Number.isInteger(min) || min < 0) {
+    throw new Error(`Invalid <x-input-${type}> min in ${use.origin.path}.`)
+  }
+  return {
+    type,
+    name: use.props.name!,
+    value: use.props.value!,
+    label: use.props.label!,
+    required: "required" in use.props,
+    min,
+  }
+}
+
+export function textFrom(
+  use: ViewComponentUse,
+  type: InputText["type"],
+): InputText {
+  return {
+    type,
+    name: use.props.name!,
+    label: use.props.label!,
+    ...(use.props.placeholder ? { placeholder: use.props.placeholder } : {}),
+    required: "required" in use.props,
+  }
+}
+
+function validateUse(
+  source: Source,
+  tag: string,
+  props: Readonly<Record<string, string>>,
+  schema: StandardSchemaV1,
+) {
+  const result = schema["~standard"].validate(props)
+  if (result instanceof Promise) {
+    throw new Error(
+      `Input View Component schema for <${tag}> must be synchronous.`,
+    )
+  }
+  return result.issues?.length
+    ? `Invalid <${tag}> props in ${source.path}: ${formatSchemaIssues(result.issues)}`
+    : undefined
+}
+
+function schemaFor(tag: string) {
+  if (tag === "x-input-text" || tag === "x-input-textarea") return textProps
+  if (tag === "x-input-radio" || tag === "x-input-checkbox") {
+    return optionProps
+  }
+  if (tag === "x-input-submit") return submitProps
+}
+
+function controlFrom(use: ViewComponentUse, tag: string) {
+  if (tag === "x-input-text") return textFrom(use, "text")
+  if (tag === "x-input-textarea") return textFrom(use, "textarea")
+  if (tag === "x-input-radio") return optionFrom(use, "radio")
+  if (tag === "x-input-checkbox") return optionFrom(use, "checkbox")
+}
+
+function inspectAuthoredInputSource(source: Source): InputAuthoringResult {
+  const controls: Array<InputChoice | InputText> = []
+  const issues: string[] = []
+  const completionBlocks: Array<Readonly<{ key: string }>> = []
+  const sourceConfig = inputResponseConfig(source)
+  if (
+    !sourceConfig &&
+    !source.body.includes("<x-input-") &&
+    !source.body.includes("input-response:")
+  ) {
+    return Object.freeze({
+      controls: Object.freeze(controls),
+      completion: undefined,
+      issues: Object.freeze(issues),
+    })
+  }
+  if (sourceConfig?.completion) {
+    issues.push(
+      `Input completion must be authored on a Block in ${source.path}.`,
+    )
+  }
+
+  for (const block of source.blocks) {
+    const config = inputResponseConfig(block)
+    if (config?.state) {
+      issues.push(
+        `Input state binding must be authored on the Source, not ${block.path}.`,
+      )
+    }
+    let recognizedUses = 0
+    const authoredUses = block.body.includes("<x-input-")
+      ? authoredViewComponentUses(block.body)
+      : []
+    for (const authored of authoredUses) {
+      const schema = schemaFor(authored.tag)
+      if (!schema) continue
+      recognizedUses++
+      const invalid = validateUse(source, authored.tag, authored.props, schema)
+      if (invalid) {
+        issues.push(invalid)
+        continue
+      }
+      const use: ViewComponentUse = { props: authored.props, origin: source }
+      try {
+        const control = controlFrom(use, authored.tag)
+        if (control) controls.push(control)
+      } catch (error) {
+        issues.push(error instanceof Error ? error.message : String(error))
+      }
+    }
+
+    if (!config?.completion) continue
+    const authoredId =
+      typeof block.data.id === "string" && block.data.id.trim() === block.id
+    if (!authoredId) {
+      issues.push(
+        `Input completion Block ${block.path} must author a stable id.`,
+      )
+      continue
+    }
+    const key = `input/${block.id}`
+    if (key.length > 256 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(block.id)) {
+      issues.push(
+        `Invalid Input completion Block id ${block.id} in ${source.path}.`,
+      )
+      continue
+    }
+    if (!recognizedUses) {
+      issues.push(`Input completion Block ${block.path} has no Input controls.`)
+      continue
+    }
+    completionBlocks.push(Object.freeze({ key }))
+  }
+  if (completionBlocks.length > 1) {
+    issues.push(
+      `Input Source ${source.path} may declare only one completion Block.`,
+    )
+  }
+  if (completionBlocks.length && !controls.length) {
+    issues.push(`Input Source ${source.path} has no Input fields to complete.`)
+  }
+  return Object.freeze({
+    controls: Object.freeze(controls),
+    completion: completionBlocks.length === 1 ? completionBlocks[0] : undefined,
+    issues: Object.freeze(issues),
+  })
+}
+
+export function inspectInputSource(
+  source: Source,
+  authoring: readonly InputAuthoring[] = [],
+) {
+  const inspected = [
+    inspectAuthoredInputSource(source),
+    ...authoring.flatMap((contributor) => {
+      const contribution = contributor.inspect(source)
+      return contribution ? [contribution] : []
+    }),
+  ]
+  const completions = inspected.flatMap(({ completion }) =>
+    completion ? [completion] : [],
+  )
+  const issues = inspected.flatMap(({ issues }) => issues ?? [])
+  if (completions.length > 1) {
+    issues.push(`Input Source ${source.path} has multiple completion units.`)
+  }
+  return Object.freeze({
+    controls: Object.freeze(inspected.flatMap(({ controls }) => [...controls])),
+    completion: completions.length === 1 ? completions[0] : undefined,
+    issues: Object.freeze(issues),
+  })
+}

package/plugins/input/config.ts

@@ -0,0 +1,85 @@
+import { canonicalSourceId } from "../../canonical.ts"
+import type { PathMXDataSchema } from "../../schema/standard.ts"
+import type { SourceNode } from "../../source/index.ts"
+
+export type InputResponseConfig = Readonly<{
+  state?: string
+  completion?: true
+}>
+
+function issue(message: string, path?: string) {
+  return {
+    issues: [{ message, ...(path ? { path: [path] } : {}) }],
+  }
+}
+
+function parseInputResponseConfig(value: unknown) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return issue("Expected an object")
+  }
+  const inputResponse = value as Record<string, unknown>
+  const extra = Object.keys(inputResponse).find(
+    (key) => key !== "state" && key !== "completion",
+  )
+  if (extra) return issue("Unknown Input Response field", extra)
+
+  let state: string | undefined
+  if (inputResponse.state !== undefined) {
+    if (
+      typeof inputResponse.state !== "string" ||
+      !inputResponse.state.trim()
+    ) {
+      return issue("Expected a canonical Source id", "state")
+    }
+    state = inputResponse.state.trim()
+    try {
+      canonicalSourceId(state)
+    } catch {
+      return issue("Expected a canonical Source id", "state")
+    }
+  }
+  if (
+    inputResponse.completion !== undefined &&
+    inputResponse.completion !== true
+  ) {
+    return issue("Expected true", "completion")
+  }
+  return {
+    value: Object.freeze({
+      ...(state ? { state } : {}),
+      ...(inputResponse.completion === true
+        ? { completion: true as const }
+        : {}),
+    }),
+  }
+}
+
+const InputResponseJsonSchema = Object.freeze({
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    state: { type: "string", pattern: "^/" },
+    completion: { const: true },
+  },
+})
+
+export const InputResponsePropSchema: PathMXDataSchema<
+  unknown,
+  InputResponseConfig
+> = {
+  "~standard": {
+    version: 1,
+    vendor: "pathmx",
+    validate: parseInputResponseConfig,
+    jsonSchema: {
+      input: () => InputResponseJsonSchema,
+      output: () => InputResponseJsonSchema,
+    },
+  },
+}
+
+export function inputResponseConfig(node: Pick<SourceNode, "data">) {
+  if (!Object.hasOwn(node.data, "input-response")) return
+  const result = parseInputResponseConfig(node.data["input-response"])
+  return "value" in result ? result.value : undefined
+}