@markgrafhq/markgraf-react 0.0.37 → 0.0.41

package/README.md

@@ -15,6 +15,16 @@ Import the package CSS for player styling:
 import "@markgrafhq/markgraf-react/css";
 ```
 
+## Browser requirements
+
+The default Canvas renderer compiles and renders in an inline Web Worker. It
+requires Workers, transferable OffscreenCanvas, FinalizationRegistry, and
+worker-side CSS Font Loading; Content Security Policies must permit
+`worker-src blob:`. Fonts load before `ready` becomes true.
+
+There is no automatic renderer fallback. Select `renderer="svg"` explicitly
+when a main-thread SVG player is required.
+
 ## `<MarkgrafPlayer src=... />`
 
 Headless component that draws the scene directly into the selected Canvas2D, SVG, or WebGL surface. Bring your own controls.
@@ -39,6 +49,9 @@ export default function App() {
 
 ## `useMarkgraf(src, opts?)` — custom UI
 
+Markgraf does not draw scene names into the diagram. Render `api.keyframe` in
+your own player shell when the current scene name should be visible.
+
 ```jsx
 import { useMarkgraf } from "@markgrafhq/markgraf-react";
 
@@ -49,6 +62,12 @@ export function Player({ src }) {
     <div>
       <canvas ref={api.elementRef} style={{ width: 600 }} />
       <button onClick={api.toggle}>{api.playing ? "Pause" : "Play"}</button>
+      <button
+        disabled={!api.ready}
+        onClick={() => api.playPrevious({ duration: 0.8, easing: { bounce: 0 } })}
+      >
+        Rewind one cue
+      </button>
       <input
         type="range"
         min={0}
@@ -75,11 +94,91 @@ export function Player({ src }) {
 | `playing`      | `boolean`                             |                                                    |
 | `duration`     | `number`                              | total seconds; 0 until `ready`                     |
 | `ready`        | `boolean`                             | true after parse + layout + first render           |
-| `play()`       | `() => void`                          |                                                    |
+| `play(options?)` | `(options?: MarkgrafPlaybackOptions) => void` | ordinary playback, optionally directional/looped |
 | `pause()`      | `() => void`                          |                                                    |
 | `toggle()`     | `() => void`                          |                                                    |
-| `seek(t)`      | `(seconds: number) => void`           | clamped to `[0, duration]`, pauses playback        |
+| `seek(t)`      | `(seconds: number) => void`           | clamped to `[0, duration]`; retains playing/paused state |
 | `setSpeed(x)`  | `(speed: number) => void`             | `1.0` is normal                                    |
+| `cues`, `steps` | readonly cue arrays | stable IDs, scheduler indices, timestamps, and graph paths |
+| `seekCue(id)`, `seekStep(name)` | `(string) => void` | seek to an explicit cue or named step |
+| `playToCue(id, options?)`, `playToStep(name, options?)` | bounded playback | stop exactly at the selected target |
+| `playNext(options?)`, `playPrevious(options?)` | bounded playback | next/previous matching cue, or end/start boundary |
+| `onCueEnter(fn)`, `onStepEnter(name, fn)` | return an unsubscribe function | cue events in traversal order |
+| `onComplete(fn)` | returns an unsubscribe function | target/boundary completion, not cancellation |
+
+### Finite spring-shaped bounded playback
+
+All four bounded methods accept the same options:
+
+```js
+const options = { duration: 0.8, easing: { bounce: 0 } };
+api.playToCue(cueId, options);
+api.playToStep("received", options);
+api.playNext(options);
+api.playPrevious(options);
+```
+
+`easing: {}` or `easing: { bounce: 0 }` opts into finite, monotonic
+spring-shaped motion. The playhead never overshoots the target, lands exactly
+at its timestamp, and has zero endpoint velocity. This is built into Markgraf:
+no Motion installation, React animation loop, or timers are needed.
+
+The clock starts when the shared engine accepts the command (in the worker for
+Canvas). Dropped frames do not extend the move: the first frame at or after its
+deadline renders the exact target and emits completion.
+
+- With `easing` or `arrival`, a positive finite `duration` (seconds) wins over
+  `speed`. Otherwise the duration is derived once from the distance and the
+  normalized supplied speed, or current speed when omitted.
+- These options are local to that move. Calling `setSpeed` during it changes
+  subsequent runs, not the current move's captured deadline.
+- Without either new field, bounded playback remains constant-speed with
+  legacy **speed-first** precedence over duration.
+- Invalid/nonpositive durations are ignored. Zero-distance moves complete
+  immediately without an arrival pulse.
+- `stopAt: ["step"]` or `["tokenLine"]` filters next/previous selection; when
+  no matching cue remains, those methods move to the end/start boundary.
+
+### Optional arrival emphasis
+
+Playhead bounce must be `0`; other values throw. For a visual bounce, explicitly
+select the arriving node instead. For example, if `"received"` is a step and
+`"api"` is a node inside `"cluster"`:
+
+```js
+api.playToStep("received", {
+  duration: 0.8,
+  arrival: { node: "api", path: ["cluster"], bounce: 0.25 },
+});
+```
+
+`arrival` alone also opts into timed spring-shaped playback. It does not infer
+a node from the cue, token, or camera. `node` is the exact node ID; `path` is the
+ancestor-node path, outermost first, and defaults to `[]` for a root-level node.
+Only that node is emphasized. Its scale pulse occupies the last 45% of the
+move, grows to `1.08`, then springs back to normal by the deadline. Arrival
+`bounce` defaults to `0.25`; finite values are clamped to `[0, 1]`.
+
+### Events and cancellation
+
+Subscribe after `api.ready`; subscriptions made before a player exists are
+no-ops. Retain and call each returned unsubscribe function (for example in a
+React effect cleanup); register anew after a source/renderer remount.
+
+```js
+const unsubscribe = api.onComplete(event => {
+  console.log(event.reason, event.time); // "target" or "boundary", exact time
+});
+// Later: unsubscribe();
+```
+
+Cue events follow scheduler-index order in the direction of travel, including
+coincident cues up to the chosen target, not beyond it. Completion is emitted
+exactly once, after cue events and the paused state update. React state becomes
+visible on its next render; `event.time` is the authoritative completion time.
+Pausing, seeking, starting a replacement move, or unmounting cancels the
+current bounded move and clears arrival emphasis without emitting completion.
+All seek methods retain the existing playing/paused state; a seek is not a pause.
 
 ### Renderer choice
 

package/dist/CommitMono-LICENSE.txt

@@ -0,0 +1,90 @@
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/Ilisarniq-Italic-LICENSE.txt

@@ -0,0 +1,37 @@
+End User Licence Agreement (EULA)
+Fonderie Typographique Coppers and Brasses
+Version 2.0 issued in February 2015
+
+
+
+The following is an agreement between the user (You) and Fonderie Typographique Coppers and Brasses (Coppers and Brasses). If you do not accept the terms, you may not complete the purchase of the font software license.
+
+¶What you are purchasing from Coppers and Brasses is a license to use font software. You are not purchasing the copyright of the typeface, but the rights to use the font software.
+
+¶The fonts are provided in OpenType (OTF) format. Additional formats are available upon request, and may require the purchase of a different license.
+
+¶You may install and use the font software on the number of computers stated on your receipt. Their geographical location is not limited but the users must belong to the same organization or household.
+
+¶You may back up the font files, but remember that they will stay available for download in your account on our website.
+
+¶You will not distribute the font software to anyone not covered by the license. A copy of the font software may be sent to a prepress bureau, if absolutely necessary. The prepress bureau must however agree to this license agreement and delete the font software when done with the work commissioned by the user.
+
+¶You may modify the font software for your own purposes, but the copyright remains with Coppers and Brasses and the terms of the license agreement remain the same. You may not sell or give away modified versions of the font software.
+
+¶You may not commission a third party to modify the font software without Coppers and Brasses’ written permission.
+
+¶You may embed the font software in a Portable Document Format (PDF), but you will take all reasonable care to embed the font software in a secure way.
+
+¶You will not embed the font files in e-books, applications or other software without a proper app-license. Contact us for more information about app-licenses.
+
+¶You may use images created using the font software on the web, but you will not host font software files on the web without a proper web-license. Contact us for more information about web-licenses.
+
+¶You will not use the font software to produce alphabet products such as, but not limited to: house numbers, stamp sets, rub-on letters, adhesive letters, alphabet punch, die sets or other methods for use in making such products. Any such use requires the purchase of a special license. Contact us for more information about this type of licensing.
+
+If you do experience any difficulties with our font software within 90 days after the purchase, we will work with you to resolve any technical issues related to it. If, after we have worked to resolve any technical issues, you are still not satisfied with our software, we will be pleased to refund your money, which shall be the limit of our liability in this transaction.
+
+Coppers and Brasses reserves the right to amend or modify this License Agreement at any time and without prior notification.
+
+For any licensing situations not covered in this agreement, please contact us.
+
+Thank you : )

package/dist/Ilisarniq-LICENSE.txt

@@ -0,0 +1,106 @@
+End User License Agreement
+
+Coppers and Brasses
+
+1. Definitions
+
+"Licensor" is the company providing the License to the Licensee, in this case, Fonderie Typographique Coppers and Brasse Inc., Coppers and Brasses or the Foundry.
+
+"Licensee" is the entity or organisation purchasing a License to use the Font Software.
+
+"Licensee Size" is the total number of employees, including temporary staff, working for the licensee.
+
+"Font Software" refers to the Font Files (Fonts) specified on the sales receipt.
+
+"Designer" is any entity (such as a design agency or studio, individual designer, or other service bureau) that provides services to the Licensee involving use of the Fonts.
+
+"Subcontractor" is any third party using the Fonts on behalf of the Licensee. Unless the Designer and Licensee are the same entity (i.e. the Designer is creating work for their own organisation), the Designer is a Subcontractor of the Licensee.
+
+
+2. Agreement and grant of rights
+
+The following is a legal agreement between Fonderie Typographique Coppers and Brasses Inc. (Coppers and Brasses, the Licensor) and You (the Licensee, whose name is specified during the checkout process and appears on the sales receipt).
+
+By purchasing, downloading, installing and or using the Font Software, You acknowledge that you have read, understood, and agree to be bound by the terms of this End User License Agreement (EULA, License or Agreement).
+
+What You are purchasing from Coppers and Brasses is a License to use the Font Software for the purposes allowed by this agreement. Once the full payment for the appropriate License is processed, Coppers and Brasses will issue You a limited, non-exclusive, non-transferable, non-assignable License for the use of the Font Software.
+
+You are not purchasing the rights of the Font Software. Coppers and Brasses together with any successors and assigns retain all rights to the Font Software, the trademarks, the copyrights and the designs embodied in the Font Software. You hereby agree that this term is contractual in nature and that the unauthorized use of the design of the Font and/or the Font Software shall be an infringement of Coppers and Brasses’ rights, causing significant monetary harm. Any rights that are not specifically given by us in this Agreement are reserved.
+
+
+3. License Scope
+
+All Licensing is one-time, perpetual, and upgradable. If your current use of the Font Software exceeds the use allowed by your License, You agree to immediately contact Coppers and Brasses to purchase an upgrade to the License. 
+
+This License allows the Licensee to use the Font Software within the organization (or by the entity) specified on the sales receipt.
+
+The fonts are provided in OTF (OpenType CFF), TTF (OpenType TrueType), WOFF, WOFF2 and EOT (Embedded OpenType) formats. Additional formats may be available upon request.
+
+You may install the Font Software on any number of devices within your organization. You may use the Font Software on any number of websites owned and controlled by your organization. You may embed the Font Software in static documents (such as PDFs), eBooks, digital products, installable applications and other media produced for your organisation. 
+
+You may only serve the Fonts on websites using the CSS @font-face rule.
+
+You may not host the Font Software on any public servers or repositories (ex: Github, Amazon S3, etc.) where they would be accessible to unlicensed third parties.
+
+You may not modify, change, alter, edit, decompile, reverse engineer, disassemble, convert, reformat, or create derivative works of the Font Software in any way.
+
+You may not commission a third party to modify the Font Software without the prior written permission of Coppers and Brasses.
+
+You may not distribute, sell, lend, sublicense, gift, make available, lease and/or rent the Font Software to any third party (unless specifically permitted in this agreement).
+
+You may not transfer this Agreement or any of your rights hereunder to any third party without the prior written permission of Coppers and Brasses.
+
+You may not use the Font Software in any application in which an unlicensed third party could use it to customise their own designs or create static documents, images, videos, animations (such as but not limited to an online design application or print-on-demand services).
+
+You may not use the Font Software to produce alphabet products such as, but not limited to: house numbers, stamp sets, rub-on letters, adhesive letters, alphabet punch, die sets or other methods for use in making such products. Any such use requires the purchase of a special License. Contact us for more information about this type of licensing.
+
+
+4. Subcontractors
+
+A Commercial License permits any number of Subcontractors to use the Fonts, in accordance with this Agreement, on behalf of the Licensee. You are permitted to send copies of the Fonts to Subcontractors for this purpose. You must ensure that any Subcontractor has read and agreed to the terms of this Agreement before receiving the Fonts.
+
+If a Subcontractor stops working for the Licensee, they must destroy all copies of the Fonts in their possession. At no time is any Subcontractor permitted to use the Fonts on behalf of themselves or any party other than the Licensee.
+
+Unless a specific exception is granted by Coppers and Brasses, a Subcontractor must not be a subsidiary or parent organisation of the Licensee.
+
+
+5. Purchase by a designer
+
+A Designer can purchase a Commercial license on behalf of the Licensee (their client), provided that: the Licensee and Licensee Size are correctly specified during the checkout process; the Licensee has read and agreed to the terms of this Agreement; and the Licensee has expressly permitted the Designer to complete the purchase on their behalf.
+
+The Designer is not permitted to quote or invoice the Licensee for any price other than the amount they actually paid for the license.
+
+
+6. Warranty
+
+If you encounter an issue or problem with the Font Software, Coppers and Brasses will make a good faith effort to provide a fix or replacement within 30 days of being notified. If the issue cannot be reasonably remedied, Coppers and Brasses may at their discretion offer to refund you, at which point this Agreement will immediately terminate. This shall be the limit of our liability in this transaction. In no event shall any liability of Coppers and Brasses exceed the purchase price of the License for the Font Software or replacement of the Font Software itself.
+
+Coppers and Brasses shall in no event be liable to you or any other third party for any direct, indirect, consequential or incidental damages arising out of the use or inability to use the Fonts, even if notified in advance.
+
+You agree to indemnify and hold Coppers and Brasses harmless from and against any claims or damage which may result from your misuse of the Fonts or breach of this Agreement.
+
+7. Legal
+
+This License Agreement is subject to and governed by the laws of Canada.
+
+This License Agreement is effective upon full payment of the amount charged for the License. This License may be terminated without notice if You breach and/or fail to comply with any term or terms contained herein.
+
+Coppers and Brasses reserves the right to amend or modify this License Agreement at any time and without prior notification.
+
+This Agreement constitutes the entire understanding between Coppers and Brasses and the Licensee (You) and supersedes all previous agreements, promises, representations and negotiations between the parties, wether verbal or in writing.
+
+No amendment, modification or waiver will be valid or enforceable unless materialised in an agreement signed by Coppers and Brasses.
+
+If any part of this Agreement is found void or unenforceable, it will not affect the validity of the rest of the Agreement, which shall remain valid and enforceable according to its terms. 
+
+The failure or election not to enforce a provision of this Agreement by Coppers and Brasses is not a waiver of its right to do so later.
+
+The numberings and section titles within this Agreement are for convenience and shall not affect or alter the meaning or construction of any terms or provisions of the Agreement.
+
+
+
+For any licensing situations not covered in this agreement or if you have any questions regarding this Agreement, please contact us at hello@coppersandbrasses.com.
+
+Thank you.
+
+Version 5.0 issued in June 2022

package/dist/markgraf-react.css

@@ -26,11 +26,16 @@
 .markgraf-embed svg[data-mg="stage"] {
   width: 100%;
   height: auto;
+  min-height: 180px;
   display: block;
   max-height: var(--mg-max-height, 90svh);
   object-fit: contain;
 }
 
+.markgraf-embed canvas[data-mg="stage"] {
+  aspect-ratio: 16 / 9;
+}
+
 .markgraf-embed :focus,
 .markgraf-embed :focus-visible {
   outline: none;

package/dist/markgraf-react.d.ts

@@ -6,12 +6,29 @@ import type { FC, MutableRefObject } from "react";
 export type MarkgrafCueKind = "step" | "tokenLine";
 export type MarkgrafPlaybackDirection = "auto" | "forward" | "backward";
 
+/** Finite, monotonic spring-shaped playhead easing; it never overshoots. */
+export interface MarkgrafPlaybackEasing {
+  bounce?: 0;
+}
+
+/** Optional visual pulse on exactly one node, independent of the playhead. */
+export interface MarkgrafArrival {
+  node: string;
+  /** Ancestor node IDs, outermost first. Omit for a root-level node. */
+  path?: string[];
+  /** Defaults to 0.25; finite values are clamped to [0, 1]. */
+  bounce?: number;
+}
+
 export interface MarkgrafPlaybackOptions {
   direction?: MarkgrafPlaybackDirection;
   speed?: number;
+  /** Seconds for a bounded move; with easing/arrival, takes precedence over speed. */
   duration?: number;
   loop?: boolean;
   stopAt?: MarkgrafCueKind[];
+  easing?: MarkgrafPlaybackEasing;
+  arrival?: MarkgrafArrival;
 }
 
 export interface MarkgrafCueBase {
@@ -50,8 +67,8 @@ export interface MarkgrafCompleteEvent {
 
 /**
  * Reactive view of a mounted markgraf player.  `time`, `keyframe`, and
- * `playing` update on every animation frame; the imperative methods are
- * stable across renders.
+ * `playing` update on every animation frame. Imperative methods address the
+ * currently mounted player, including when retained across renders.
  *
  * `elementRef` is typed by the renderer you chose:
  * - default / `"canvas"` → `Ref<HTMLCanvasElement | null>`
@@ -78,7 +95,7 @@ export interface MarkgrafApi<E extends Element = HTMLCanvasElement> {
   playWith(options?: MarkgrafPlaybackOptions): void;
   pause(): void;
   toggle(): void;
-  /** Clamped to `[0, duration]`.  Pauses the player. */
+  /** Clamped to `[0, duration]`. Cancels a bounded move but preserves playing/paused state. */
   seek(seconds: number): void;
   seekCue(cueId: string): void;
   seekStep(stepName: string): void;
@@ -86,7 +103,7 @@ export interface MarkgrafApi<E extends Element = HTMLCanvasElement> {
   playToStep(stepName: string, options?: MarkgrafPlaybackOptions): void;
   playNext(options?: MarkgrafPlaybackOptions): void;
   playPrevious(options?: MarkgrafPlaybackOptions): void;
-  /** `1.0` is normal playback speed. */
+  /** `1.0` is normal. Does not change an opted-in move's captured deadline. */
   setSpeed(speed: number): void;
   onCueEnter(callback: (cue: MarkgrafCue) => void): () => void;
   onStepEnter(stepName: string, callback: (cue: MarkgrafStepCue) => void): () => void;