Extension usage (v0.2.x)

This page covers the Page Proxy extension workflow in v0.2.x: sidepanel tools, code editor behavior, and selector popup flow.

Sidepanel layout and shortcuts

The sidepanel has:

• A code editor panel at the top.
• A tool panel at the bottom.
• A toolbar on the top for switching tools.

Toolbar shortcuts:

• Shift + 1: Select
• Shift + 2: Create
• Shift + 3: Selectors
• Shift + 4: Help
• Shift + 5: Export

Code editor

The editor is where you edit code and run it on the active tab.

What it does:

• Keeps pa, pn, pq, ps, pt, and pv imports in your script.
• Uses a selector definition block:
  • // ==Selectors==
  • // ==/Selectors==
• Parses script metadata and selector definitions as you edit.
• Autosaves after a short delay when content changes.
• Supports manual save with Ctrl+S / Cmd+S.
• Runs your script with the Run button (play icon).
  • Script runs with a 2-second timeout.
  • If the run button is still disabled even after 2 seconds, it's a bug, please report it.
• Stores state per website/tab context.

On protected pages (for example browser internal pages), editing and execution are disabled and a protected-page message is shown.

Select tool

Use Select to inspect elements on the current page.

1. Activate Select (Shift + 1).
2. Click an element on the page.
3. Review captured properties in the Select panel.
4. Use the parent button (up arrow) to move one level up in the DOM.
5. Click Selector to open selector editing, or CSS to open CSS editing.

DevTools integration:

• When browser DevTools is open on the active tab, a wrench button appears in Select.
• Toggle the wrench button to follow the element selected in DevTools Elements panel.
• Parent selection and selector/CSS opening use that DevTools-backed selection while follow mode is enabled.

Selector editor

The selector editor opens from Select -> Selector.

What you do:

1. Edit the generated pq.selector(...) code in the popup editor.
   • You can name the variable and the name property to be whatever you want.
2. Use the live preview snippet for the active property/filter.
3. Drag the preview grip into the selector code editor to insert filter fragments.
4. Save the selector.

What happens on clicking Save:

• The sidepanel validates the snippet contains pq.selector.
• It requires a const assignment.
• It checks variable-name collisions.
• If valid, it inserts the selector into the editor selector block.

CSS inspector

The CSS inspector opens from Select -> CSS and is also available from the popup mode switch (pp-api -> CSS).

What you do:

1. Edit CSS selector + declaration text directly.
2. Inspect selector parts and property values in the right panel.
3. Edit computed style values in-place to generate declarations.
4. Hold z to preview matching elements and x to preview applied styles.
5. Optionally remove :nth-of-type(...) quickly.

Changing the selector updates baseSelector in the selector popup, so no need to edit it manually.

What happens on clicking Save:

• The popup inserts a ps.injectCSS(...) snippet using your current selector and declarations in the Selectors block.

Create tool

Create is currently marked as coming soon.

Planned direction in the UI:

• Generate reusable components.
• Build script settings UI and other script-driven UI pieces.

Selectors tool

Selectors shows selector entries parsed from your selector block in the editor.

For each selector, the tool displays:

• Selector name.
• Rule count.
• Parsed rules and helper usage extracted from the selector matches function.

Use this to confirm selectors were saved correctly and to quickly audit selector logic.

Help tool

Help contains quick project references:

• Documentation link.
• Permission request flow for @grant values (for example run-on-page-load).
• Known issues list.
• Planned features and roadmap links.
• Content fetched from the GitHub repository at extension/HELP.md, rendered as markdown.

Use it as the first stop when behavior seems unexpected.

Export tool

Export packages your current script from the editor.

Current behavior:

• pp-script export is available now.
• Other formats are visible but marked coming soon.
• Exported filename is derived from script title metadata.