Live URL ======== Instead of a static wireframe HTML file, you can point guidestar at a **live URL** — any same-origin page that renders the real application. This is useful when: * your application is already deployed and you want demos that always reflect the current UI without maintaining a separate wireframe file; * you are documenting a tool that lives on the same server as your docs (e.g. a GitHub Pages–hosted utility alongside your Sphinx site). .. note:: **Same-origin requirement.** The browser's ``fetch()`` API enforces the `Same-Origin Policy`_. A live URL will only load without extra configuration when the demo page and the target URL share the same origin (scheme + host + port). Cross-origin URLs require the target server to send ``Access-Control-Allow-Origin`` CORS headers. GitHub Pages automatically serves permissive CORS headers for all files, so any two pages under the same GitHub Pages site (e.g. ``https://yourorg.github.io/yourrepo/``) are same-origin and load without restriction. .. _Same-Origin Policy: https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy How it works ------------ The ``htmlSrc`` option accepts any URL. At page-load time guidestar calls ``fetch(htmlSrc)``, parses the response as HTML, scopes the wireframe's styles via CSS ``@scope`` to prevent leakage into the host page (see :ref:`css-isolation`), and injects the body content into the demo container. From that point the demo behaves identically to one backed by a static wireframe file. .. code-block:: json { "htmlSrc": "https://spacetelescope.github.io/guidestar/demo-builder.html", "viewport": 1440, "initSteps": [ {"target": "#recording-body", "action": "add-class", "value": "collapsed"}, {"target": "#steps-body", "action": "add-class", "value": "collapsed"} ], "steps": [ {"target": "#source-url", "action": "highlight", "delay": 1200, "caption": "Enter the URL of your wireframe"} ] } In RST: .. code-block:: rst .. guidestar-demo:: https://spacetelescope.github.io/guidestar/demo-builder.html :viewport: 1440 :steps-json: [{"target":"#source-url","action":"highlight","delay":1200}] Embedding as an iframe (recommended for docs) --------------------------------------------- When multiple demos on a single docs page each load a heavy live URL, the page would make many ``fetch()`` requests and inject the full application DOM multiple times. A lighter pattern is to: 1. Create one self-contained demo HTML file per step (containing the ``data-guidestar-config`` and the two asset tags). 2. Deploy those files alongside your application on the same server. 3. Embed them in RST using ``.. raw:: html`` `` The ``loading="lazy"`` attribute defers fetching until the iframe scrolls into view, keeping the initial page-load fast. Preventing user interaction with the source -------------------------------------------- When using a live URL, the injected page is fully functional — buttons, links, accordions, and forms all work. For demo purposes you almost always want to **prevent** viewers from interacting with the content so they don't accidentally navigate away, collapse a section mid-step, or submit a form. Guidestar's ``allowUserInteractions`` option (default: ``false``) places a transparent glass pane over the demo content. All clicks on the content area toggle play/pause instead of reaching the underlying page. The playback controls, timeline, and fullscreen button are above the pane and always usable. .. code-block:: json { "htmlSrc": "https://example.com/app.html", "allowUserInteractions": false } In RST (the default — you don't need to specify it explicitly): .. code-block:: rst .. guidestar-demo:: https://example.com/app.html To **allow** interaction (e.g. you want viewers to try the UI themselves while the demo is paused): .. code-block:: rst .. guidestar-demo:: https://example.com/app.html :allow-user-interactions: true :pause-on-interaction: true .. note:: ``:pause-on-interaction:`` only takes effect when ``:allow-user-interactions: true``. With the default ``false``, all content-area clicks are handled by the interaction blocker and ``:pause-on-interaction:`` is ignored. For live URL sources, **always leave** ``allowUserInteractions`` at its default (``false``). A viewer clicking a link in the embedded live page could navigate the live application to an unexpected state with no way to undo it short of a full reload. .. note:: With ``allowUserInteractions: false``, the overlay that intercepts clicks also prevents text selection inside the demo. Viewers cannot copy text, URLs, or code snippets shown in the content. If your demo contains copyable text (e.g. a command shown in a terminal pane), set ``allowUserInteractions: true`` — but only when using a static wireframe where there is no risk of real navigation. Never set it to ``true`` for live-URL sources. Restart and timeline seek behaviour ------------------------------------- By default, guidestar restores the demo to its initial state by setting ``_contentRoot.innerHTML`` back to a snapshot taken after the first ``fetch()`` and re-executing any inline ``