@pathmx/player 0.5.0 → 0.5.1

package/README.md

@@ -1,80 +1,38 @@
 # `@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.
+Focused reading and slide presentation experiences for PathMX documents.
 
-Install the plugin and author its app component where the Player should exist:
+## Install
 
-```md
-<x-player-app />
+```sh
+bun run pmx plugins add player
 ```
 
-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  |
+```ts
+// plugins/player.plugin.ts
+export { default } from "@pathmx/player"
+```
 
-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.
+Most applications should install [`@pathmx/paths`](https://www.npmjs.com/package/@pathmx/paths)
+instead. It includes Player with Path and Completion.
 
-## Source authoring
+## Use Player
 
-Give an explicit Beat a stable fragment when it should be directly linkable:
+Place the Player app in any Markdown Source that should offer Play mode:
 
 ```md
-<p data-pmx-beat="course-goals">Name the three course goals.</p>
+# Course introduction
 
-[Return to the course goals](#course-goals)
+<x-player-app />
+
+Welcome to the course.
 ```
 
-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`.
+Open the Source with `?play=focus` for focused reading or
+`?play=presentation` for slides. Player also remembers choices made through
+its on-page controls.
 
-Choose a built-in slide theme in Source frontmatter:
+Choose a default theme in Source frontmatter:
 
 ```md
 ---
@@ -83,79 +41,17 @@ play:
 ---
 ```
 
-Choose reusable composition directly in Block topmatter:
-
-```md
-<!--
-layout: media-end
--->
-
-# A slide title
+Available themes are `native`, `editorial`, `signal`, and `code`. Block
+topmatter can set `play.variant` to `cover`, `section`, `quote`, `fact`,
+`full`, or `end`.
 
-![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`:
+Give an important Beat a stable link target with `data-pmx-beat`:
 
 ```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.
+<p data-pmx-beat="course-goals">Name the three course goals.</p>
 ```
 
-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.
+Then link directly to `?play=presentation#course-goals`.
 
-## 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" />} />
-```
+Keyboard controls use the arrow keys to move, `Space` for the next Beat, `G`
+for the Block grid, `M` to switch mode, and `Escape` to close or exit Player.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pathmx/player",
   "description": "Focused reading and presentation experiences for PathMX.",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "react-dom": ">=19.0.0"
   },
   "dependencies": {
-    "@pathmx/react": "0.5.0",
+    "@pathmx/react": "0.5.1",
     "lucide-react": "^1.34.0"
   }
 }