[@layout]: ./releases.layout.md # Releases What's new in PathMX. All releases are currently beta. [@link.play Play release notes](./releases.changelog.md) · [Install PathMX](../docs/start/install.guide.md) · [CLI reference](../docs/cli.reference.md) --- ## 0.7.2 - **[Give your site a fresh look.](../docs/site/themes.reference)** Paper, Studio, Terminal and Synthwave have refreshed typography, colors and self-hosted fonts. Docs has a new reading layout and simpler mobile navigation. - **[Publish full-text RSS feeds.](../docs/site/feeds.reference)** The new Feed plugin turns an authored query into an RSS feed, with complete article content and links that work in feed readers. - **[Keep saved work on your main branch.](../docs/hosting/deployment.reference#saved-work)** Deploy checkpoints content saved on the running site and brings it back to the shared branch, so authors and the site work from the same history. - **[Use the CLI while your site is running.](../docs/cli.reference)** Source edits and Plugin commands coordinate with the running server. Windows startup and path handling are repaired, and piped commands return their complete output. - **[Apply saved preferences before the page appears.](../docs/extend/state.reference#style-the-first-paint)** Components can use Settings to restore document styling before first paint and keep it in sync across tabs. - **[Keep custom Plugin data live.](../docs/extend/plugins.reference#refresh-plugin-state)** Plugin routes can refresh the views that depend on their saved data, preserving each reader's access and unfinished input. - **Build editors with shared operations.** Plugins can use public interactions and move existing Blocks while retaining their identities. Block edits preserve unrelated Source metadata. - **Keep reading and saving reliably.** Sign-in restores styles without a reload, live updates no longer interrupt normal navigation, and sites with long editing histories retain less recovery data without losing retry receipts. ### Upgrading to 0.7.2 Upgrade official packages together and run your project's checks before deploying. - **Deploy:** follow the [runner bootstrap and branch migration](../docs/hosting/deployment.reference#move-off-live-branch) before using the new runner. Remove `replicate`; declare every site-editable file or directory in `liveSources`. Review saved work before resolving any migration conflict. - **Themes:** review your site's typography and mobile layout. Glass and Bauhaus are now [example stylesheets](../docs/site/theme-a-site.guide), rather than built-in presets; copy the stylesheet if you use either. - **Development servers:** restart existing servers to pick up the linked-Plugin watcher and running-host CLI changes. --- ## 0.7.1 - **[Build branching surveys and forms.](../docs/authoring/input.reference#conditional-questions)** Checkbox questions can cap selections and offer an exclusive “none of these” choice, follow-up questions can depend on earlier multi-select answers, and answers to questions that are no longer shown are not saved. [Reporting labels](../docs/authoring/input.reference#describe-questions-for-reporting) describe each question for dashboards and exports. - **[Guide people through a form one question at a time.](../docs/learning/player.reference#guide-a-form)** Player can open a questionnaire directly as a guided form with participant controls, sections and skips, saving as people go and resuming at their first unanswered question. - **Move through Player more easily on phones and keyboards.** One Back and Next pair replaces tap zones, slides scroll naturally on phones and stay in place when the keyboard opens, and ⌘/Ctrl+Enter saves the response you are editing. - **[Give a folder its own presentation.](../docs/site/layouts.reference#select-a-layout)** A folder's index can set default layouts and a theme for every page inside it. The nearest index wins, and `theme: false` clears an inherited theme. - **[Retry saves without saving twice.](../docs/extend/actions.reference#retry-a-save)** A save can carry a request identifier, so retrying after a dropped connection returns the original result. Durable jobs can [run an Action as a step](../docs/extend/jobs.reference#save-an-action-as-a-step) that is not repeated on replay. - **[Build richer custom answer editors.](../docs/authoring/input.reference#extend-a-response-editor)** One component can edit several fields of a response, repeated components on a page keep separate identities, and saving several Blocks together reports success accurately. - **[Review learners' work and manage sessions clearly.](../docs/accounts/auth.reference#user-admission-and-optional-homes)** Staff can review learner Homes read-only, shared folders admit reviewers through their member list, and signed-in people without a Home can see who they are and sign out. Development sign-in works through one configured HTTPS origin, such as a tunnel. - **Keep working when something is wrong.** A malformed Source is set aside with a diagnostic instead of stopping the site, CLI edits made while `pmx dev` runs are handed to the running server, and [`pmx mv`](../docs/cli.reference#mv) moves individual assets and updates links to them. Every heading has a permalink, and pages declare their canonical URL for search engines and agents. ### Upgrading to 0.7.1 Upgrade official packages together and run `bun run pmx lint` before deploying. - **Staff and shared-folder access.** `role: staff` reviews current Actor Homes read-only. A shared folder admits a reviewer only through its `members` list; add reviewers there when they need a shared folder. - **Card links inside paragraphs.** A rich reference inside a paragraph now fails lint instead of failing when the page renders. Put each card link on its own line. - **Duplicate ids.** Each rendered id now appears once, so live updates stay stable. A hand-written id that repeats a Block or heading id is removed with a lint warning; link to that Block or heading instead. Two hand-written elements with the same id fail lint, and the second loses its id. - **Nested folder indexes.** A nested `index.md` that sets `theme:` or default layouts now applies to the pages beneath it. Review nested indexes that previously had no effect. - **Conditional answers.** Answers submitted for questions hidden by their conditions are rejected. Input no longer shows a separate completion message beside the save button; the button shows the saved state. - **Invalid Actors.** An invalid Actor Source is denied with a diagnostic instead of stopping startup. --- ## 0.7.0 - **Build reusable interactive components with less wiring.** Components declare their properties, server-loaded data, rendering, browser behavior and styles together, with typed references to separate modules when needed. - **Sign in across devices.** Optionally send a one-time email code alongside the sign-in link, with a refreshed, customizable sign-in form. - **Set limits for written responses.** Add character or word limits to text fields. The browser and server enforce them while preserving over-limit drafts for correction. - **Keep local development sign-ins across restarts.** The standard development user chooser remembers sessions until sign-out or expiry. - **Remove completed tasks without blocking deployment.** Saved completion history remains intact when an authored target is removed, and progress counts only current targets. Deployment checks the candidate against a copy of live Sources before stopping the running service. - **Keep reading and interaction controls working together.** Reference panels load their behavior reliably, page outlines link to the displayed content, floating controls respect reserved footer space, and small video players keep their controls accessible. - **Recover from interrupted uploads.** An upload that fails before creating a file can be retried without leaving subsequent reads blocked. ### Upgrading to 0.7.0 Start with the [0.7 migration guide and agent prompt](../docs/start/migrate-070.guide). This release changes custom Plugin and Component authoring. Migrate `defineAppComponent` declarations to `defineComponent`, use named Action and Query context arguments, and update renderer/client module references before deploying. Follow the current [Plugin](../docs/extend/plugins.reference), [Component](../docs/authoring/components.reference) and [Action](../docs/extend/actions.reference) contracts. Upgrade official packages together and verify custom Plugins against the same release. Back up durable Sources and private Plugin state before upgrading. Auth adds a session-storage migration; downgrading packages alone cannot roll it back. Recovery requires compatible application and state versions, with any newer saved work reconciled before restoring a backup. --- ## 0.6.8 - **Keep your place while the site updates.** Live changes elsewhere on the page preserve unchanged content, drafts, keyboard focus, and Player position—even when other users are saving work. - **Start using Assessment with one command.** Run `bun run pmx plugins add assessment` to install and activate questions and submissions without writing a repository Plugin. Custom evaluators and Completion remain available through repository configuration. --- ## 0.6.7 - **Render directories and query-driven pages faster.** Core avoids repeated work when preparing component rows, checking public content, resolving local routes, and formatting schedules. Permission and source changes still take effect immediately. - **Keep development pages working as projects grow.** Browser dependency watching shares subscriptions across package directories, reducing filesystem watcher exhaustion and recovering from failed subscriptions. - **Load live pages without a redundant fetch.** The browser confirms the initial page before fetching again, while still catching changes made as live updates connect. - **Keep your development viewing user across code restarts.** The development switcher preserves your selected user until you end the session or stop the dev command. - **Keep Player navigation and actions consistent.** Entering Player preserves the current Path and query context. Linked cards and image links expose working actions, including keyboard activation. --- ## 0.6.6 - **[Guide people through a Path.](../docs/learning/path.reference)** Ordered activities show progress, dates, and locations, with previous/next navigation and a full Path outline that stays available in Focus and Slides. - **[Reuse activities with different settings.](../docs/authoring/reuse-content.guide#reuse-a-source-as-separate-attempts)** Source instances let the same content have its own progress and property overrides, including deadlines and locations. - **Show when and where activities happen.** Built-in [Schedule](../docs/authoring/sources.reference#schedules) and [Location](../docs/authoring/sources.reference#locations) support event times, deadlines, live-now signals, physical places, and online meeting links. - **[Organize content into tabs.](../docs/authoring/blocks.reference#groups-and-displays)** Group consecutive Blocks into labeled tabs while keeping their content available to links and Player. - **Customize sign-in and email.** Brand [sign-in and recovery](../docs/accounts/auth.reference), and use authored [Email templates](../docs/email.reference) or custom delivery for messages. - **[Keep floating controls together.](../docs/extend/core.reference#shared-control-surfaces)** Path, Player, and participating utility controls share a responsive dock, consistent sizing, and coordinated visibility in Play. - **[Help visitors recover from missing pages.](../docs/start/publish.guide#missing-pages)** Sites now have themed 404 pages and can author their own recovery content for live and static hosting. --- ## 0.6.5 - **Generate pages from your data.** The new [Generate Plugin](../docs/authoring/generate.reference) turns JSON or CSV records into Markdown Sources using templates, with saved recipes and previews before writing. - **Collect Analytics on Cloudflare sites.** Static sites can now collect page views and activity, retain observations across deployments, and provide private reports and exports through the [Analytics CLI](../docs/hosting/analytics.reference#report-from-a-static-cloudflare-site). - **Return to private pages after signing in.** Opening a private page now takes visitors through sign-in and back to the page they requested, including its query parameters. - **Keep canonical URLs current while browsing.** Navigating between pages now updates or removes the canonical URL, including when using Back. --- ## 0.6.4 - **Embed posts, videos, and web pages.** The new [Embed Plugin](../docs/authoring/embed.reference) displays X posts, YouTube videos, and rich link cards, with access to the original source in Player. - **Add sound to your content.** The new [SFX Plugin](../docs/authoring/sfx.reference) adds sound effects and loops to interactions and presentation moments, with shared mute and volume controls. - **Move whole folders with the CLI.** [`pmx mv`](../docs/cli.reference#mv) moves pages and assets together and updates supported links, layouts, and query scopes. External URLs remain intact, and you can preview changes before applying them. - **Read action labels in Player.** Presentation actions show their labels beside their icons, making controls easier to identify. ### Upgrading custom Player integrations Replace `pmx:beatenter` listeners with `player:beat-enter` and update handlers to the [current event detail](../docs/learning/player.reference#lifecycle-events). --- ## 0.6.3 - **Create and manage short URLs.** The new [Short Plugin](../docs/site/short.reference) lets you give pages custom URLs and change where those URLs lead without breaking existing links. - **See how people use your site.** The new [Analytics Plugin](../docs/hosting/analytics.reference) adds live reports of page views and activity, with control over what you collect and how long you keep it. - **Stay signed in longer.** Sign-ins now last 30 days by default and renew as you use the site. Site owners can adjust the duration. - **Share folders with selected people.** Set access once for a folder and its pages and files. Restrict individual pages or subfolders further when needed. - **Make section links more reliable.** Links to headings land in the right place, Back shows current content, and mobile navigation stays steady while scrolling. ### Upgrading a live site Private Plugin databases now live in `db/`. Stop writers and back up existing `.pathmx/state/` databases before moving them, or explicitly retain the old location with `PATHMX_DB_DIR`. Keep databases outside Git and update backup jobs. Move Actor `home` declarations to the Home directory index as `access: { type: home, owner: /people/ada.user }`. Older unbound Auth sessions and magic links are invalidated during the credential migration; users sign in again. Existing account records and authored work remain intact. --- ## 0.6.2 - **Find pages listed in directories.** Pages included in query-built directories now appear in site search, sitemaps, and AI-readable site listings, while respecting who can read them.

Upgrade notes — Plugin authors

Await `app.sources.discoverable(view)` when discovering readable pages from a Plugin.

--- ## 0.6.1 - **Move between pages without the fade.** Pages update immediately, and recently visited pages can reopen faster—including with Back and Forward—while keeping content current. - **Make linked content easier to find.** Site search, sitemaps, and AI-readable site listings now follow readable links throughout your site, including links in layouts and navigation. Unlinked pages still work at their direct URLs. - **Add custom URLs from Plugins.** Plugins can publish documents and redirects alongside site pages, including in static exports. See the [route API](../docs/extend/plugins.reference#http-routes). - **Keep your chosen appearance.** The color-scheme toggle remembers your preference as you navigate and reload, while respecting the site's theme settings. - **Start presentations in Slides.** Player opens new presentations in Slides, with step-by-step controls and working checkboxes. Explore the [color experiment](../examples/color-context.demo). --- ## 0.6.0 - **Let browser agents interact with your site.** [WebMCP](../docs/extend/webmcp.reference) lets agents use forms, presentation controls, and file uploads, with control over which actions they can take. - **Deploy sites that save people's work.** [Server deployment](../docs/hosting/deployment.reference) publishes updates from the CLI while backing up and preserving live content and private data. - **Show each reader their own content.** [View bindings](../docs/authoring/queries.reference#view-bindings) display profiles and responses in pages and components, with fallbacks when a value is unavailable. ### Authoring and interactive content - **Learn by building.** Expanded [documentation](../docs/index.md) covers authoring, publishing, and agent workflows. [Build a workshop site](../docs/start/build-a-site.guide.md) with layouts, navigation, themes, and components. - **Reuse components across pages.** [Components](../docs/authoring/components.reference) accept content and named sections consistently, whether written in Markdown or a Plugin. [Queries](../docs/authoring/queries.reference) can fill them with content the reader is allowed to see. - **Link directly to a presentation.** Create shareable links that open Player in Focus or Slides. Try the [Opera Game](../examples/chess/opera-game.demo) or [color experiment](../examples/color-context.demo). - **Follow progress where you work.** Links in a learning path show progress for their destinations, and `/~` opens your personal Home. - **Create link-preview images.** The [Share Plugin](../docs/authoring/sources.reference#generate-a-share-image) generates a themed preview image for a page to use when its link is shared. - **Explore connected pages.** The [Graph Plugin](../docs/site/graph.reference) adds backlinks and interactive connection maps that respect reader access. - **Set up forms and assessments.** New guides cover [Input forms](../docs/authoring/input.reference), [Assessment](../docs/learning/assessment.reference), and [saved browser state and settings](../docs/extend/state.reference). - **Publish apps with browser storage.** [Browser publications](../docs/extend/core.reference#browser-publications) let people keep their work in the browser across visits. - **Play video in a lesson.** [Video](../docs/authoring/video.reference) supports hosted videos and your own files with shared playback controls. - **Keep interactions steady.** Forms preserve their controls during live updates. Player keeps your place during rapid keyboard navigation and restores multi-column layouts.

Migration notes — components and Path progress

Replace `defineViewComponent` with `defineComponent`, and `` with ``. Plugin component `render()` receives children and named slots through `use.slots`. See [Components](../docs/authoring/components.reference.md). Layouts use one `` outlet; the table of contents is ``. In Plugin components, `use.origin` is the authoring Source and `ctx.sourceId` is the displayed page. Read the latter through `ctx.view.readSource(ctx.sourceId)` for controls authored in a layout. A session may now be `local`. Only anonymous sessions provide `signIn`; branch on `session.type` before using credential-specific properties. Explicit native Action targets require `data-pmx-action-target` on the form alongside one hidden `_target` field. See [Actions](../docs/extend/actions.reference.md#native-forms). Custom compositions now use `createPathPlugin({ completion: completion.reader })`. Remove `targets: [path.completion]`; use `await completion.reader.summary(view, source)` for Source summaries. The `@pathmx/paths` preset handles this composition automatically. Manual Path-Step Completion facts no longer determine progress. Progress comes from the linked Source's requirements; authored Step ids remain required.

--- ## 0.5.7 ### Search your site - **Find pages and sections.** The optional Search Plugin respects reader access, stays current as content changes, and works on static sites. Try **Search** in this site's header. - **Know where you are.** Breadcrumbs show the page's location, and [shared navigation](../docs/site/navigation.reference) highlights the current page. --- ## 0.5.6 ### A steadier local workflow - **Run the right version.** The CLI uses your project's pinned PathMX version, even when run from a nested folder. Production serving loads your project settings and shuts down cleanly. - **See style edits live.** Changes to imported stylesheets appear without restarting development. Explore the [theme gallery](../examples/theme-gallery.demo). - **Keep content and progress current.** New folders appear as you add them, people can upload attachments to their own work, and progress displays stay consistent across page and interactive views.

Upgrade notes

Pin application `@pathmx/*` dependencies to `0.5.6`, update plugins with `pmx plugins update`, and run `pmx lint`. No content or State migration is required.

--- ## 0.5.3 ### Personal work and learning paths - **Define who can act on your site.** Mark the people or other entities that can own work and perform actions. - **Keep responses in readable files.** Form answers, submission times, and progress are stored in each person's Home, where you can inspect and edit them. - **Build nested learning paths.** Organize steps into paths within paths, respect reader access, and use completed forms and attachments to determine progress. - **Run Actions from Plugins.** Plugins can invoke existing Actions to reuse site behavior.

Migration notes — Actor State and Plugin APIs

Pin application `@pathmx/*` packages to `0.5.3`, mark Actor Sources with `actor: true`, and convert legacy Input State before upgrading. Replace the `yaml @state` fence and nested status records with frontmatter `values` and `submissions: { response: timestamp }`. Run `pmx lint` before deployment. Plugin composers (`createInputPlugin`, `createCompletionPlugin`, `createAssessmentPlugin`, and `createPathPlugin`) expose their instance through `.plugin`. Use `app.rewriteHtml` for application HTML rewriting, import schemas from `zod`, and use `tx.readSource()` to inspect staged Sources in Actions.

--- ## 0.5.2 ### Predictable page addresses - **Control page URLs through file names.** Moving a page changes its address and updates links to it. See [Sources](../docs/authoring/sources.reference). - **Keep system files out of your site.** Dependency, Git, and generated-output folders are excluded from content discovery and live updates. - **Recognize successful CLI updates.** An unrelated malformed global dependency no longer makes a successful `pmx update` appear to have failed.

Migration notes — Source ids

Remove Source-level `id` fields reported by `pmx lint`; rename the file to change its identity or route. Authored Block ids remain supported.

--- ## 0.5.1 ### One install for Paths - **Set up a learning site with one package.** The Paths preset brings together learning paths, progress tracking, and presentations. Add sign-in and diagrams when needed. - **Get started with clearer guides.** Package READMEs include installation steps and working examples. The [first-site guide](../docs/start/first-site.guide) walks through creating your site. - **Load installed Plugins reliably.** Plugin assets load from their installed locations, including after development restarts. --- ## 0.5.0 ### The first public beta Build interactive sites and learning experiences from Markdown files. The first release includes learning paths, progress tracking, presentations, sign-in, assessments, diagrams, React components, and Cloudflare publishing. [Build your first site](../docs/start/first-site.guide).