Replace Screenshot Placeholders
Every guide declares a stable ID and future WebP path. ScreenshotPlaceholder renders a polished instruction frame until that exact file exists, then automatically renders the image.
Each page declares an exact screenshot contract: stable ID, future file path, state, viewport, visible controls, alt text, caption, annotations, and redaction. At build time the component checks whether that WebP exists. Until it does, readers see a useful capture brief; after it is added, the same page automatically shows the real image.
Begin by find the screenshot id in the page or inventory. The work pays off when you run validation/build and inspect light/dark/mobile rendering and alt/caption context; that final observation is more meaningful than a saved notice because it shows what an administrator or visitor actually receives.
What this feature does and when to use it
Section titled “What this feature does and when to use it”Use this system to create consistent, accessible, privacy-safe evidence of the audited UI.
Use this feature in the following situations:
- You are replacing one placeholder with an audited staging capture.
- A plugin UI change makes an existing screenshot inaccurate and it must be recaptured.
- You are checking that every image is unique, accessible, organized, and free of sensitive information.
Where to find it
Section titled “Where to find it”Before you begin
Section titled “Before you begin”- A staging WordPress site with synthetic content and no real secrets or conversations.
- The viewport, capture state, alt text, caption, annotations, and redaction rules from audit/screenshot-inventory.md.
- An image editor that can permanently redact pixels and export WebP.
Set it up step by step
Section titled “Set it up step by step”- Find the screenshot ID in the page or inventory.
- Prepare the exact synthetic screen state and viewport.
- Capture only the meaningful UI area with enough context for navigation.
- Permanently redact secrets, names, user content, IPs, tokens, private URLs, and browser/account chrome.
- Add minimal numbered annotations only when requested.
- Export to the exact lowercase kebab-case .webp path under public/images/screenshots.
- Run validation/build and inspect light/dark/mobile rendering and alt/caption context.
Fields, controls, and important values
Section titled “Fields, controls, and important values”Screenshot fields do not change the assistant; they make each procedure easier to recognize and safer to maintain. A precise state and annotation can show an administrator where a response-related setting lives, while redaction prevents the guide from exposing credentials or conversations. The inventory keeps future captures consistent without rewriting each page.
| Field, control, or status | What SmartSite Assistant does with it | How to use it and why it matters |
|---|---|---|
| Stable ID | Unique page-derived identifier used by validation and the rendered frame. | Keep the page-derived identifier unchanged when replacing an image so validation, inventory, and the rendered placeholder continue to refer to the same capture contract. Rename it only as part of an intentional route migration. |
| Expected path | Exact /images/screenshots/{section}/{page}.webp path. | Export the optimized WebP to the declared section and filename. The exact path is the replacement mechanism, so a similar filename elsewhere will leave the placeholder visible even if the image exists. |
| Build-time replacement | The component checks for the local public file; no page edit is required. | During the build, the component checks whether the declared public asset exists and chooses the image or capture brief. Authors therefore add the file without rewriting generated pages or removing useful placeholder instructions. |
| Alt / caption | Describe purpose and screen, not decorative details or hidden sensitive content. | Describe why the screen matters and the state a reader should recognize. Avoid listing every decorative detail, and never include hidden secrets or personal information in text merely because pixels were redacted. |
| Inventory | Generated from the same catalog so IDs/paths/capture instructions remain aligned. | Use the generated inventory to schedule captures, reproduce the correct state, apply annotations consistently, and verify redaction. Because it shares catalog data with the page, a mismatch is easier to detect before publication. |
How to confirm it is working
Section titled “How to confirm it is working”For Replace Screenshot Placeholders, a saved notice is only the beginning. Confirm the outcome from a fresh session and compare it with the success description above so cached pages or earlier conversation context do not create a false positive.
Practical example
Section titled “Practical example”Add public/images/screenshots/knowledge/sync-statuses.webp to replace only that guide’s placeholder.
Recommended practice
Section titled “Recommended practice”- Change one part of Replace Screenshot Placeholders at a time and keep a short record of the previous value and test result.
- Verify the saved result in the screen, visitor session, or connected service that actually consumes the setting.
Important warnings
Section titled “Important warnings”Common problems and focused checks
Section titled “Common problems and focused checks”| Problem | What to check and what to do next |
|---|---|
| Replace Screenshot Placeholders is missing or does not match this guide. | Confirm the plugin is active and the account can manage WordPress options. Regenerate source-derived files and run the complete documentation validation before publishing the result. |
| A change on Replace Screenshot Placeholders does not produce the expected result. | Keep the exact notice and test case, then review the browser console and WordPress/PHP log. Regenerate source-derived files and run the complete documentation validation before publishing the result. |
Commands
Section titled “Commands”Validate inventory and replacement
Section titled “Validate inventory and replacement”npm run validatenpm run buildScreen reference
Section titled “Screen reference”- Capture
- Show one placeholder frame next to the real replacement at its exact path, with the matching inventory row.
- Show
- Stable ID, path, capture brief, placeholder, real WebP, inventory
- Viewport
- Desktop, 1440 × 900
- Annotate
- Use numbered callouts only for controls referenced in the procedure.
- Redact
- OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text