AI Assisted from URL
====================

Use this prompt when you have access to a running instance of the application
and want the agent to render the page and reproduce it as a wireframe.  The
prompt instructs the agent to use Playwright at a full laptop viewport,
capture all meaningful UI states, inline icons and images, reproduce
hover/click/interaction styles, and sanitize any external calls.

Because the wireframe is designed at a specific viewport width, use the
``:viewport:`` directive option (e.g. ``:viewport: 1440``) so guidestar
scales it correctly at any container size.

.. code-block:: text

   You are helping me build a guidestar wireframe — a self-contained HTML
   mockup used to animate a UI demo in documentation.

   Please prompt for a URL and then produce a single file called wireframe.html that reproduces the
   layout, visual style, and interactive affordances of that page.

   Follow these steps:

   1. **Render the page at a laptop viewport and capture each meaningful state.**
      Launch Playwright with a viewport of 1440 × 900 (a standard laptop
      resolution).  Navigate to the URL and wait for network-idle.
      Then *interact* with the page to reach each meaningful UI state
      (open a panel, submit a search, expand a dropdown, etc.) and take a
      full-page screenshot of each state.  These screenshots are your
      reconstruction reference.  Note the exact viewport width (1440) —
      you will need to record it so the guidestar directive can be told to
      render the wireframe at that width and scale it to fit.

   2. **Extract colours, spacing, and typography from rendered elements.**
      Do NOT attempt to fetch and inline external stylesheets.  Modern
      JavaScript frameworks inject all CSS at runtime; there are no static
      sheets to fetch.  Instead, call ``window.getComputedStyle()`` on a
      representative sample of elements (header, body background, buttons,
      input fields, table rows, badges, status bars) to read the actual
      background colours, text colours, border colours, border radii, font
      families, font sizes, and padding.  Collect these values in a
      palette table before writing any CSS.

   3. **Capture and inline custom icons and images.**
      For each non-text icon or image visible on the page:
        a. Try ``page.evaluate()`` to read any inline SVG source directly
           from the DOM (``el.outerHTML`` for ``<svg>`` elements, or
           ``el.src`` / ``el.currentSrc`` for ``<img>``).
        b. **Prefer SVG over raster formats.**  If the source image is a
           PNG, GIF, or JPEG, do **not** inline it as a base64 ``data:``
           URI — instead redraw it as a minimal inline SVG that reproduces
           the shape, colours, and general composition.  Raster images
           (especially GIFs) may be animated; a static wireframe only ever
           shows one frame, which is often incomplete.  Use the Playwright
           screenshot of the rendered element as your visual reference.
           Only fall back to a base64 ``data:`` URI if the image cannot be
           reasonably approximated as SVG (e.g. a photographic background).
           In that case apply the ~20 KB size limit from the previous rule.
        c. For icon-font glyphs (Material Icons, Font Awesome, etc.), look up
           the rendered text content or ``aria-label`` and substitute an
           equivalent unicode character or a minimal inline SVG path.

   4. **Capture hover, focus, and click interaction styles.**
      For each interactive element (buttons, links, checkboxes, tabs,
      dropdowns):
        a. Use ``page.hover(selector)`` to trigger the hover state, then
           read ``getComputedStyle()`` for background, border, and text
           colour changes.  Add a ``:hover`` rule (or a ``.hover`` class
           variant) that reproduces these.
        b. Use ``page.focus(selector)`` similarly to capture focus rings.
        c. For click/active states, read any CSS ``transition`` and
           ``animation`` properties and reproduce them with equivalent
           ``@keyframes`` or ``transition`` declarations in the wireframe.
        d. For dropdowns: click the trigger element to open the dropdown,
           capture the fully-rendered option list (text content, selected
           state, colours), and model the open state as a CSS class variant
           (e.g. ``.dropdown.open .dropdown-menu { display: block; }``).
           Hard-code the option list HTML with the real values from the page.
      These interaction styles should be pure CSS — no JavaScript.

   5. **Reconstruct HTML from scratch — do not copy the rendered DOM.**
      Framework SPAs produce thousands of lines of auto-generated wrappers.
      Use the screenshots, the computed-style palette, and the accessibility
      tree snapshot as references, then write clean minimal HTML from scratch
      that reproduces the layout visible in the screenshots.

      Pay special attention to **scrollable content regions** (forms,
      lists, or result tables that scroll independently while a header
      or action bar stays fixed).  These are easy to model incorrectly
      because a block element whose content is shorter than the viewport
      will look correct at full height but will silently refuse to scroll
      when embedded in a constrained container.  Use the following flex
      containment pattern for any column that must scroll:

      .. code-block:: css

         /* Root element: fill the container in embedded mode */
         .app { height: 100%; min-height: 0; display: flex; flex-direction: column; }

         /* Every flex ancestor in the scroll chain must opt out of
            min-height:auto (the default), otherwise overflow is suppressed */
         .scrollable-region { flex: 1; min-height: 0; overflow-y: auto; }

         /* Sticky footers inside the column must not shrink */
         .action-bar { flex-shrink: 0; }

      Key rules:

      - Use ``height: 100%`` (not ``min-height``) on the root element so
        that a guidestar embedded container limits the height.
        ``min-height`` overrides ``height`` and prevents the flex chain
        from constraining the scrollable child.
      - Add ``min-height: 0`` to every flex item in the chain between the
        root and the scrollable leaf.  Without it, flex's default
        ``min-height: auto`` allows the child to grow past its allocated
        space and the scrollbar never appears.
      - Give the scrollable leaf ``overflow-y: auto`` (or ``scroll``).
      - Give any non-scrolling sibling (action bar, footer) ``flex-shrink: 0``
        so it is never squeezed out of view.

      After writing the CSS, open the file in a browser window sized to the
      design viewport and **manually resize the window to a smaller height**.
      If an action bar disappears or content leaks below the bottom edge,
      the flex chain is still wrong.

      Pay special attention to **sticky/fixed bars** (headers, footers,
      toolbars that remain on screen while the main content scrolls).
      These are easy to under-represent because they sit outside the
      scrollable area and may be partially off-screen when you take a
      full-page screenshot.  For each bar:

      - Take a dedicated screenshot of the bar at full viewport width
        before reconstructing it.  List every control it contains,
        including secondary buttons that flank the primary action — they
        are easy to miss if you only read the DOM without looking.
      - Reproduce relative button widths faithfully: use ``flex: 1`` (or
        equivalent proportional sizing) on buttons that visually dominate
        the row; avoid fixed padding values that produce wrong proportions
        at different container widths.
      - If a status or summary line appears on a separate row within the
        bar, render it as a distinct child element beneath the button row,
        not as an inline sibling in the same flex row.

   6. **Add IDs to interactive elements.**
      For every button, input, select, tab, accordion, and toggleable panel,
      ensure there is a unique ``id`` attribute so that guidestar step
      selectors can target them.

   7. **Model multi-state UI with root-level class toggles.**
      For each distinct page state (search form vs. results, panel open vs.
      closed, banner visible vs. dismissed), define a CSS class on the root
      element that switches the layout::

        /* default */
        .results-view { display: none; }
        .search-view  { display: flex; }

        /* results state — toggled by add-class on #app */
        #app.results-open .search-view  { display: none; }
        #app.results-open .results-view { display: flex; }

      The CSS class toggles above are what guidestar's ``add-class`` /
      ``remove-class`` steps modify during the automated demo.  They should
      also be wired up so a user who clicks manually gets the same result.
      After writing the CSS, add a small ``<script>`` block at the bottom of
      ``<body>`` that attaches a ``.onclick`` handler for each interactive
      element (use ``.onclick =`` not ``addEventListener`` so that guidestar
      can safely re-run the block on restart without stacking duplicate
      listeners).  The handlers should only toggle the same CSS classes the
      guidestar steps use — no ``fetch()``, timers, or DOM creation.

   8. **Sanitize external references.**
      - Remove or stub out any ``<script>`` tags other than the interaction
        handler block added in step 7 (i.e. remove framework bundles,
        analytics, loaders).
      - Replace ``href`` / ``action`` on ``<a>`` and ``<form>`` with ``"#"``.
      - Remove all framework event-handler attributes (``onclick``,
        ``onsubmit``, etc.) that came from the original DOM — the interaction
        handlers from step 7 use ``.onclick`` property assignment instead.
      - Replace any remaining external image URLs with neutral placeholders
        (light-grey background or inline SVG) if not already inlined in
        step 3.
      - Remove ``<meta http-equiv="...">`` refresh or CSP tags.
      - Double-check: no ``fetch()``, ``XMLHttpRequest``, ``WebSocket``, or
        timer calls should remain in the final script block.

   9. **Write wireframe.html.**
      One self-contained HTML file: single ``<style>`` block in ``<head>``,
      no ``<script>`` tags, no external stylesheets, no external images or
      fonts.  Record the viewport width used (``1440``) in a comment at the
      top of the file so the guidestar ``:viewport:`` option can be set
      correctly.

   Verify by opening wireframe.html in a browser at 1440 × 900 and
   comparing it against each Playwright screenshot.  The two should look
   substantially the same.

   Verify the output by opening wireframe.html in a browser and comparing it
   visually against the Playwright screenshots for each state.  The two
   should look substantially the same at the same viewport size.


Worked example — MAST HST Search
---------------------------------

The wireframe at
`examples/wireframes/mast-hst.html <../../examples/wireframes/mast-hst.html>`_
was produced by applying the "From a live web URL" prompt to
`https://mast.stsci.edu/search/ui/#/hst/ <https://mast.stsci.edu/search/ui/#/hst/>`_.
The resulting file captures both the search-form state and the results-table
state as pure-CSS class variants (``#mast-app.results-open``).

.. guidestar-demo:: _static/mast-hst.html
   :steps: #input-objects@1800:type-text=M31|Enter a target name, #btn-resolve@1200:click|Resolve the coordinates, #toggle-dtype-all@1000:remove-class=active|Deselect All data types, #toggle-dtype-spectrum@1000:add-class=active|Select Spectrum only, #mast-app@400:add-class=banner-closed, #input-program-id@1200:type-text=14657|Enter a program ID, #input-pi@1200:type-text=Postman|Enter PI surname, #input-exposure@1000:type-text=1200|Enter exposure time in seconds, #input-obs-start-from@1400:scroll-to|Scroll to output column selector, #btn-select-recommended@1200:click|Select recommended columns, #btn-search@1200:click|Click SEARCH, #mast-app@600:add-class=results-open|Results table appears, pause@1500, #row-28@1400:add-class=highlighted|Scroll down to inspect a result, pause@1200, #row-28@400:remove-class=highlighted, #btn-edit-search@1200:click|Return to search form, #mast-app@400:remove-class=results-open, pause@1500
   :height: 540px
   :viewport: 1440
   :repeat: true