@pathmx/player 0.5.0

package/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:
+
+chevron-down, chevron-up, external-link, play, x
+
+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/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,161 @@
+# `@pathmx/player`
+
+`@pathmx/player` turns a rendered PathMX document into focused reading or a slide
+presentation. It derives its route from semantic HTML in the browser, so Sources
+stay ordinary Markdown. Core image directives compile into portable metadata,
+which Player projects into presentation frames before deriving that route.
+
+Install the plugin and author its app component where the Player should exist:
+
+```md
+<x-player-app />
+```
+
+The package default-exports `PlayerPlugin` for application/plugin composition.
+Most applications install it transitively through the `@pathmx/paths` preset.
+
+## Test Play
+
+Use `?play=focus` for reading or `?play=presentation` for slides. The current
+settings model also supports `intensity=low|medium|high`,
+`play-theme=native|editorial|signal|code`, `play-guide=off`, and
+`play-notes=off`. The last-used controls are remembered locally; an active
+Play URL records the resolved shareable state.
+
+High intensity hides upcoming Beats completely while keeping previously viewed
+Beats visible at a reduced opacity.
+A Play URL opens at its public Beat fragment or the first Beat. Beats with
+public fragments keep the URL current for copying, history traversal, and
+reloads at the same point. Fragment-free URLs always start from the beginning;
+private session state never changes where a shared URL opens.
+
+In presentation mode Player owns browser scroll restoration. It re-anchors the
+active Beat after initial load and persisted-page restoration so the viewport
+cannot drift away from the progress state when an iOS browser view restores an
+older document offset.
+
+The maintained acceptance fixtures are:
+
+- `/demos/block-layouts.demo`
+- `/demos/play-reading-gauntlet.demo?play=focus`
+- `/demos/play-deck-gauntlet.demo?play=presentation`
+- `/demos/play-media-hints.demo?play=presentation`
+- `/demos/play-theme-gallery.demo`
+
+Keyboard controls:
+
+| Shortcut                  | Result                          |
+| ------------------------- | ------------------------------- |
+| `Command/Control + Enter` | Start Play with saved settings  |
+| `↑` / `↓`, `Space`        | Previous / next Beat            |
+| `←` / `→`                 | Previous / next Block           |
+| `G`                       | Toggle the Block grid           |
+| `M`                       | Change between Focus and Slides |
+| `+` / `-`                 | Raise / lower intensity         |
+| `Escape`                  | Close the grid, then exit Play  |
+
+Inside the Block grid, arrow keys move between the actual rendered Blocks and
+Enter/Space selects a Block's first Beat. The grid is temporary; selecting a
+Block updates the current shareable Beat without adding browser-history noise.
+
+## Source authoring
+
+Give an explicit Beat a stable fragment when it should be directly linkable:
+
+```md
+<p data-pmx-beat="course-goals">Name the three course goals.</p>
+
+[Return to the course goals](#course-goals)
+```
+
+Player compiles `id="course-goals"` into the server-rendered HTML when the
+element does not already have an ID. Authored IDs are always preserved, and
+Markdown headings already work as native fragments. Add the Play query to a
+link that should enter directly into Play, for example
+`?play=presentation#course-goals`.
+
+Choose a built-in slide theme in Source frontmatter:
+
+```md
+---
+play:
+  theme: editorial
+---
+```
+
+Choose reusable composition directly in Block topmatter:
+
+```md
+<!--
+layout: media-end
+-->
+
+# A slide title
+
+![Diagram](./diagram.png)
+```
+
+The core Block layouts are `center`, `media-start`, and `media-end`; they also
+apply outside Player. Player-only rhetorical treatments stay under
+`play.variant`:
+
+```md
+<!--
+play:
+  variant: quote
+-->
+```
+
+The Player variants are `cover`, `section`, `quote`, `fact`, `full`, and
+`end`. Tables step through body rows automatically. Code fences opt into
+line-group Beats with a compact range expression:
+
+````md
+```ts [1-2|3|5-7]
+// code
+```
+````
+
+Standalone Markdown images keep their natural size by default. Put one native
+image directive at the start of the alt text when a Block needs a different
+media treatment:
+
+```md
+![@image.fit Meaningful alt text](./diagram.png)
+![@image.fill Meaningful alt text](./photo.jpg)
+![@image.background Meaningful alt text](./photo.jpg)
+![@image.background.fit Meaningful alt text](./diagram.png)
+```
+
+`fit` contains the whole image; `fill` covers the available content area and
+becomes full-bleed in Slides mode when it is the Block's only content.
+`background` covers the Block behind its content, while `background.fit` shows
+the entire background. The core Image Plugin removes the leading directive
+from the rendered `alt` attribute, so the remaining text stays meaningful to
+readers and assistive technology.
+
+Add presenter annotations with the Deckset-style caret paragraph syntax. Each
+additional note paragraph starts with another caret:
+
+```md
+# Explain the model
+
+^ Ask for a concrete example before advancing.
+
+^ Relate the answer to the next Block.
+```
+
+Notes stay out of normal document flow and the Beat route. Slides mode shows
+the active Block's notes in an optional bottom-right annotation card.
+
+## Shared Plugin controls
+
+React-owned Plugin surfaces can import the source-owned shadcn/Base UI layer
+from `@pathmx/react/ui`. `ActionButton` is the standard accessible icon-action
+boundary; Player composition remains private to this Plugin.
+
+```tsx
+import { ActionButton } from "@pathmx/react/ui"
+
+;<ActionButton label="Open tools" icon={<ToolsIcon aria-hidden="true" />} />
+```

package/actions.ts

@@ -0,0 +1,69 @@
+import type { Beat } from "./route.ts"
+import { invokePathMXAction } from "@pathmx/react"
+import type { ActionAffordance } from "@pathmx/core"
+
+export type PlayAction = {
+  type: "action"
+  label: string
+  external: boolean
+  activate(): void
+}
+
+export type PlayerLeaf = Beat | PlayAction
+
+function actionLabel(link: HTMLAnchorElement) {
+  return (
+    link.getAttribute("aria-label") ??
+    link.textContent?.replace(/\s+/g, " ").trim() ??
+    ""
+  )
+}
+
+function playerReady(action: ActionAffordance) {
+  const required = action.input?.required
+  return (
+    !Array.isArray(required) ||
+    required.every(
+      (name) => typeof name === "string" && name in (action.boundInput ?? {}),
+    )
+  )
+}
+
+/** Project ordinary links in the active Beat into touch-friendly Play actions. */
+export function actionsForBeat(
+  beat: Beat,
+  contextual: readonly ActionAffordance[] = [],
+): PlayAction[] {
+  const links = [
+    ...(beat.element.matches("a[href]")
+      ? [beat.element as HTMLAnchorElement]
+      : []),
+    ...beat.element.querySelectorAll<HTMLAnchorElement>("a[href]"),
+  ]
+  const hrefs = new Set<string>()
+
+  return links
+    .flatMap((link) => {
+      const label = actionLabel(link)
+      const href = link.href
+      if (!label || !href || hrefs.has(href)) return []
+      hrefs.add(href)
+      const url = new URL(href, location.href)
+      return [
+        {
+          type: "action" as const,
+          label,
+          external: url.origin !== location.origin || link.target === "_blank",
+          activate: () => link.click(),
+        },
+      ]
+    })
+    .concat(
+      contextual.filter(playerReady).map((action) => ({
+        type: "action" as const,
+        label: action.title,
+        external: false,
+        activate: () => void invokePathMXAction(action),
+      })),
+    )
+}