@pathmx/path 0.5.0

package/LICENSE.md

@@ -0,0 +1,172 @@
+# PathMX Proprietary Beta License
+
+Version 0.1 — July 21, 2026
+
+Copyright © 2026 DUO Interactive, LLC.
+All rights reserved.
+
+This license governs the first-party PathMX software distributed in the npm
+package `@pathmx/core`, including its command-line interface, bundled
+library surfaces, runtime and Player components, and accompanying
+documentation (the “Software”). DUO Interactive, LLC is the “Licensor.” This
+license does not cover the private PathMX source-code repository or separately
+identified third-party materials.
+
+“Project” means Paths, Sources, responses, data, and other content authored or
+processed with the Software.
+
+“Application” means software or a service created by you in which the Software
+supports product-specific functionality but is not itself offered as a
+general-purpose PathMX product.
+
+“Redistributable Components” means runtime, Player, or library portions of the
+Software incorporated into a Project, Application, or generated output through
+ordinary use of the Software or ordinary compilation and bundling tools.
+
+“Authorized Users” means your employees and individual contractors who use the
+Software on your behalf, and your hosting, continuous-integration, and other
+service providers that possess or run necessary copies solely to provide
+services to you.
+
+## 1. Agreement
+
+By installing, accessing, or using the Software, you agree to this license. If
+you use the Software on behalf of an organization, you represent that you have
+authority to accept this license for that organization. If you do not agree,
+do not install or use the Software.
+
+## 2. License grant
+
+Subject to this license, the Licensor grants you a non-exclusive, worldwide,
+royalty-free, non-transferable, and non-sublicensable license, perpetual for
+the version of the Software to which it applies unless terminated under
+Section 10, to:
+
+- install, execute, and use the Software for personal, educational,
+  internal-business, or commercial purposes;
+- use the Software to author, integrate, build, test, serve, play, host, and
+  operate Projects and Applications;
+- import, compile, bundle, configure, and integrate the Software through its
+  documented library and command-line interfaces;
+- create and distribute independent Projects, Applications, plugins, and
+  integrations that use those interfaces without modifying the Software
+  itself; and
+- make copies reasonably necessary for local development, testing, continuous
+  integration, backup, and hosted production environments.
+
+Your Authorized Users may exercise those rights solely on your behalf. You are
+responsible for their compliance with this license.
+
+You may reproduce and distribute Redistributable Components only as
+incorporated into your Project, Application, or generated output, and only when
+you preserve applicable license and proprietary notices. You may host and
+commercially provide access to that Project, Application, or output. You may
+not distribute Redistributable Components as a standalone package or as a
+general-purpose substitute for the Software.
+
+Each lawful recipient of a Redistributable Component may execute and use that
+component, display its output, and make technically necessary transitory copies
+solely as incorporated into the Project, Application, or output in which they
+received it. This limited recipient permission does not include a right to
+extract, modify, or redistribute the component separately.
+
+## 3. Restrictions
+
+Except where applicable law does not allow the restriction, you may not:
+
+- modify, adapt, translate, or create derivative works of the Software, except
+  for the compilation, bundling, configuration, and integration expressly
+  permitted in Section 2;
+- redistribute, sublicense, sell, lease, or otherwise provide the Software to
+  another person as a standalone package, product, or service except to an
+  Authorized User or as a Redistributable Component under Section 2;
+- resell, rebrand, or provide the Software as a hosted or managed service that
+  gives third parties general-purpose access to substantial PathMX authoring,
+  building, serving, Player-administration, or library functionality for their
+  own unrelated projects;
+- reverse engineer, decompile, disassemble, or otherwise attempt to derive the
+  source code of the Software; or
+- remove or alter copyright, license, trademark, or other proprietary notices.
+
+For clarity, the managed-service restriction does not prohibit a hosted
+Project or Application in which PathMX supports the licensee's own
+product-specific experience and is not itself the general-purpose product
+offered to customers.
+
+## 4. Your content
+
+As between you and the Licensor, you retain ownership of the Paths, Sources,
+responses, data, independent application code, and other content that you
+author or provide while using the Software. You are responsible for that
+content and for having the rights needed to use it.
+
+Generated output may contain Redistributable Components or third-party
+materials. Your ownership of your content does not change the ownership or
+license terms of those components and materials.
+
+## 5. Ownership and trademarks
+
+The Software is licensed, not sold. The Licensor and its suppliers retain all
+rights in the Software not expressly granted by this license. This license
+does not grant permission to use the PathMX name, logos, or other marks except
+as reasonably necessary to identify the Software accurately.
+
+## 6. Beta status and changes
+
+The Software is a proprietary beta release. Its APIs, behavior, file formats,
+and features may change or be removed without notice. The Licensor has no
+obligation to provide support, maintenance, updates, continued availability,
+or backward compatibility. A later version may be offered under different
+license terms, including an open-source license. Different terms for a later
+version do not change the license previously granted for an earlier version.
+
+## 7. Third-party materials
+
+The Software and Redistributable Components may include or depend on
+third-party materials governed by their own license terms. Those terms control
+for the applicable third-party materials. You must preserve third-party notices
+when the applicable third-party terms require it.
+
+## 8. Disclaimer of warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED “AS IS” AND
+“AS AVAILABLE,” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS,
+IMPLIED, OR STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, OR THAT THE SOFTWARE WILL BE
+SECURE, ERROR-FREE, OR UNINTERRUPTED.
+
+## 9. Limitation of liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR AND ITS CONTRIBUTORS,
+SUPPLIERS, AND AFFILIATES WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS OF DATA,
+PROFITS, REVENUE, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING FROM OR RELATED TO
+THE SOFTWARE OR THIS LICENSE, EVEN IF ADVISED OF THE POSSIBILITY OF THOSE
+DAMAGES.
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THEIR TOTAL LIABILITY FOR ALL CLAIMS
+ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE WILL NOT EXCEED THE
+GREATER OF THE AMOUNT YOU PAID FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE
+THE EVENT GIVING RISE TO THE CLAIM OR US$100.
+
+## 10. Termination
+
+This license terminates if you materially breach it and do not cure the breach
+within thirty days after receiving written notice from the Licensor. On
+termination, you and your Authorized Users must stop using and delete your
+copies of the Software. Sections 4, 5, 8, 9, 10, and 11 survive termination.
+Termination does not withdraw the limited permission already granted by
+Section 2 to lawful recipients of Redistributable Components distributed
+before termination.
+
+## 11. General
+
+If a provision of this license is unenforceable, it will be modified only to
+the minimum extent necessary to make it enforceable, and the remaining
+provisions will continue in effect. Failure to enforce a provision is not a
+waiver. You may not assign or transfer this license without the Licensor's
+written consent. The Licensor may assign this license together with ownership
+of the Software to a successor owner. This license binds and benefits the
+permitted successors and assigns of you and the Licensor. This license is the
+entire agreement concerning the Software unless you and the Licensor have
+signed a separate agreement that expressly replaces it.

package/README.md

@@ -0,0 +1,30 @@
+# `@pathmx/path`
+
+> This package is the current proof-of-concept implementation. The replacement
+> authoring and composition contract is being shaped in
+> [Path plugin](../../apps/pathmx-site/paths/work/path.design.md).
+
+The Path semantic owner for the Paths product family. `PathPlugin` contributes
+the `path` Source schema; the same package projects viewer-readable Path
+Sources into ordered, nested steps with stable ids and guarded cycles.
+
+Use the Plugin directly when composing a product without the full Paths preset:
+
+```ts
+export { default } from "@pathmx/path"
+```
+
+`projectPath()` and `pathStepIds()` expose the Path structure to downstream
+systems. An unlabeled step derives its id from the href, so inserting Blocks
+does not orphan Completion; author `@step.<id>` when identity must survive a
+destination change. `rollupPathCompletion()` maps stable Path leaves onto a separately
+composed `@pathmx/completion` reader. `PathCompletionContributor` declares
+stable leaf `path/<step-id>` manual keys to the canonical Action; aggregate
+branches remain derived from their children:
+
+```ts
+CompletionPlugin({ contributors: [PathCompletionContributor] })
+```
+
+`@pathmx/paths` supplies that composition. Completion is an optional peer;
+installing Path alone does not install or activate it.

package/index.ts

@@ -0,0 +1,258 @@
+import {
+  definePlugin,
+  markdownListItemLink,
+  type MarkdownList,
+  type MarkdownListItem,
+  type SourceDescription,
+  type View,
+} from "@pathmx/core"
+import type {
+  CompletionContributor,
+  CompletionReader,
+  CompletionStatus,
+} from "@pathmx/completion"
+
+/** Own the ordered Path Source meaning shared by Paths product plugins. */
+export const PathPlugin = definePlugin({
+  id: "path",
+  schema: {
+    sources: {
+      path: {
+        label: "Path",
+        description: "An ordered, optionally nested sequence of Sources.",
+        icon: "route",
+        color: "emerald",
+      },
+    },
+  },
+})
+
+export default PathPlugin
+
+export type PathStep = Readonly<{
+  id: string
+  key: string
+  pathId: string
+  label: string
+  href: string
+  target?: Readonly<{ type: "source"; id: string }>
+  children: readonly PathStep[]
+  cycle?: true
+}>
+
+export type PathProjection = Readonly<{
+  source: SourceDescription["source"]
+  steps: readonly PathStep[]
+}>
+
+export type PathCompletionNode = Readonly<{
+  step: PathStep
+  status: CompletionStatus
+  complete: number
+  total: number
+  children: readonly PathCompletionNode[]
+}>
+
+type DraftStep = Omit<PathStep, "children"> & { children: DraftStep[] }
+type StepSource = Readonly<{
+  id: string
+  blocks: readonly Pick<
+    SourceDescription["source"]["blocks"][number],
+    "lists"
+  >[]
+}>
+type StepDescription = Pick<SourceDescription, "relations"> &
+  Readonly<{
+    source: StepSource
+  }>
+
+const STEP_LABEL = /^@step(?:\.([A-Za-z][\w-]*))?(?:\s+(.+))?$/
+
+function stableHash(value: string) {
+  let hash = 0x811c9dc5
+  for (let index = 0; index < value.length; index++) {
+    hash ^= value.charCodeAt(index)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(36)
+}
+
+function stepIdentity(label: string, href: string) {
+  const directive = label.trim().match(STEP_LABEL)
+  const explicit = directive?.[1]
+  return {
+    id: explicit ?? `step-${stableHash(href)}`,
+    label: directive?.[2]?.trim() || (directive ? href : label.trim()),
+  }
+}
+
+function localSteps(description: StepDescription): DraftStep[] {
+  const duplicates = new Map<string, number>()
+  function steps(lists: readonly MarkdownList[]): DraftStep[] {
+    return lists.flatMap((list) =>
+      list.type === "unordered" ? list.items.flatMap((item) => step(item)) : [],
+    )
+  }
+  function step(item: MarkdownListItem): DraftStep[] {
+    const link = markdownListItemLink(item)
+    if (!link) return []
+    const identity = stepIdentity(link.label, link.href)
+    const duplicate = duplicates.get(identity.id) ?? 0
+    duplicates.set(identity.id, duplicate + 1)
+    const id = duplicate ? `${identity.id}-${duplicate + 1}` : identity.id
+    const relation = description.relations.find(
+      (candidate) => candidate.href === link.href,
+    )
+    return [
+      {
+        id,
+        key: `${description.source.id}#${id}`,
+        pathId: description.source.id,
+        label: identity.label,
+        href: link.href,
+        ...(relation?.target ? { target: relation.target } : {}),
+        children: steps(item.children),
+      },
+    ]
+  }
+  return description.source.blocks.flatMap((block) => steps(block.lists))
+}
+
+function targetsPath(step: Pick<PathStep, "href" | "target">) {
+  if (step.target) return step.target.id.endsWith(".path")
+  const href = step.href.split(/[?#]/, 1)[0]!.replace(/\/+$/, "")
+  return href.endsWith(".path") || href.endsWith(".path.md")
+}
+
+function isBranchStep(step: Pick<PathStep, "children" | "href" | "target">) {
+  return step.children.length > 0 || targetsPath(step)
+}
+
+async function expandSteps(
+  view: View,
+  description: SourceDescription,
+  ancestors: ReadonlySet<string>,
+): Promise<readonly PathStep[]> {
+  const nextAncestors = new Set(ancestors).add(description.source.id)
+  return Promise.all(
+    localSteps(description).map((step) =>
+      expandStep(view, step, nextAncestors),
+    ),
+  )
+}
+
+async function expandStep(
+  view: View,
+  step: DraftStep,
+  ancestors: ReadonlySet<string>,
+): Promise<PathStep> {
+  const authored = await Promise.all(
+    step.children.map((child) => expandStep(view, child, ancestors)),
+  )
+  if (!step.target) return Object.freeze({ ...step, children: authored })
+  const nested = await view.describeSource(step.target.id)
+  if (!nested || nested.source.type !== "path") {
+    return Object.freeze({ ...step, children: authored })
+  }
+  if (ancestors.has(nested.source.id)) {
+    return Object.freeze({ ...step, children: authored, cycle: true })
+  }
+  const referenced = await expandSteps(view, nested, ancestors)
+  return Object.freeze({
+    ...step,
+    children: Object.freeze([...authored, ...referenced]),
+  })
+}
+
+/** Expand one visible Path into an ordered tree with guarded Path references. */
+export async function projectPath(
+  view: View,
+  id: string,
+): Promise<PathProjection | undefined> {
+  const description = await view.describeSource(id)
+  if (!description || description.source.type !== "path") return
+  return Object.freeze({
+    source: description.source,
+    steps: Object.freeze(await expandSteps(view, description, new Set())),
+  })
+}
+
+/** Return local stable step ids without resolving or expanding references. */
+export function pathStepIds(description: StepSource) {
+  const ids = new Set<string>()
+  const collect = (steps: readonly DraftStep[]) => {
+    for (const step of steps) {
+      ids.add(step.id)
+      collect(step.children)
+    }
+  }
+  collect(localSteps({ source: description, relations: [] }))
+  return ids
+}
+
+function pathLeafStepIds(description: StepSource) {
+  const ids: string[] = []
+  const collect = (steps: readonly DraftStep[]) => {
+    for (const step of steps) {
+      if (isBranchStep(step)) collect(step.children)
+      else ids.push(step.id)
+    }
+  }
+  collect(localSteps({ source: description, relations: [] }))
+  return ids
+}
+
+/** Declare stable authored Path steps to the canonical Completion Action. */
+export const PathCompletionContributor: CompletionContributor = (source) =>
+  source.type === "path"
+    ? pathLeafStepIds(source).map((id) => ({ key: `path/${id}` }))
+    : []
+
+function aggregateCompletion(
+  reader: CompletionReader,
+  actorId: string,
+  step: PathStep,
+): PathCompletionNode {
+  const children = step.children.map((child) =>
+    aggregateCompletion(reader, actorId, child),
+  )
+  if (isBranchStep(step)) {
+    const complete = children.reduce((sum, child) => sum + child.complete, 0)
+    const total = children.reduce((sum, child) => sum + child.total, 0)
+    return Object.freeze({
+      step,
+      status:
+        total > 0 && complete === total
+          ? "complete"
+          : complete > 0
+            ? "in-progress"
+            : "not-started",
+      complete,
+      total,
+      children: Object.freeze(children),
+    })
+  }
+  const complete =
+    reader.read(actorId, {
+      source: step.pathId,
+      key: `path/${step.id}`,
+    })?.outcome === "complete"
+  return Object.freeze({
+    step,
+    status: complete ? "complete" : "not-started",
+    complete: complete ? 1 : 0,
+    total: 1,
+    children: Object.freeze([]),
+  })
+}
+
+/** Roll generic Completion facts through one projected Path tree. */
+export function rollupPathCompletion(
+  reader: CompletionReader,
+  actorId: string,
+  path: PathProjection,
+): readonly PathCompletionNode[] {
+  return Object.freeze(
+    path.steps.map((step) => aggregateCompletion(reader, actorId, step)),
+  )
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pathmx/path",
+  "description": "Ordered learning-path semantics for PathMX applications.",
+  "version": "0.5.0",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pathmx/pathmx-beta.git",
+    "directory": "paths/path"
+  },
+  "homepage": "https://github.com/pathmx/pathmx-beta#readme",
+  "bugs": "https://github.com/pathmx/pathmx-beta/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "type": "module",
+  "exports": "./index.ts",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "peerDependencies": {
+    "@pathmx/completion": "^0.5.0",
+    "@pathmx/core": "^0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@pathmx/completion": {
+      "optional": true
+    }
+  }
+}