docs: page-structure screenshot + competitor comparison

README.md

@@ -14,6 +14,7 @@ development toolbar.
 
 [Product page](https://opace.agency/tools/astro/visual-editor/) ·
 [Install](#install) · [Try the demo](#try-the-repository-demo) ·
+[How this compares](#how-this-compares) ·
 [Configuration](#configuration) · [Security](./SECURITY.md) ·
 [Contributing](./CONTRIBUTING.md) ·
 [Opace open-source portfolio](https://github.com/OpaceDigitalAgency/OpaceDigitalAgency)
@@ -50,6 +51,13 @@ with a one-click explanation:
 
 ![The visual builder with a selected block toolbar, a locked chip and the docked inspector](./.github/assets/shot-builder.png)
 
+**Page structure navigator.** Every group, section, row and block on the
+page, Elementor-style: click any item to select and scroll to it on the
+canvas, drag or use move controls to reorder, and see lock state at a
+glance without opening the rendered page's own toolbar:
+
+![The Page structure navigator tree showing nested groups, sections, rows and blocks with a selected paragraph highlighted on the canvas](./.github/assets/shot-navigator.png)
+
 **SEO editing.** Title, description, keywords, canonical URL, Open Graph
 fields and robots directives in one form, each field capability-checked
 against its real source before it is offered:
@@ -157,22 +165,105 @@ This package provides:
 
 It adds no production route, editor client or public write endpoint.
 
+## How this compares
+
+Most "Astro CMS" tools solve a different problem: they give a hosted or
+admin-panel UI for editing structured content records (Keystatic, Sitepins,
+Writenex, Sveltia, Decap), or overlay a hosted headless CMS on top of a live
+preview (Sanity, Netlify Visual Editor, TinaCMS). None of them write directly
+to `.astro` source, and most need an external account or hosting.
+
+The closest actual peer is [Stacki](https://github.com/flowtricks/stacki), a
+free, open-source **desktop app** that also edits Astro projects locally with
+no CMS backend. It reaches that goal through a different mechanism: a
+component/props palette in a separate Electron app, rather than click-any-
+rendered-text editing inside Astro's own Dev Toolbar. Stacki currently ships
+a visual style panel that this package does not yet have — see
+[Roadmap](#roadmap-and-requests).
+
+|                                      | This package                                          | Stacki                      | Headless-CMS tools (Keystatic, Sitepins, TinaCMS, …) |
+| ------------------------------------ | ----------------------------------------------------- | --------------------------- | ---------------------------------------------------- |
+| Where you edit                       | In-browser, on the rendered page, via the Dev Toolbar | Separate desktop app        | Separate admin UI or hosted studio                   |
+| Writes to `.astro` source directly   | Yes                                                   | Yes, via its own page model | No — content records only                            |
+| Zero-config on an unannotated page   | Yes                                                   | No                          | No                                                   |
+| Style/design editing                 | Not yet (roadmap)                                     | Yes                         | No                                                   |
+| External account or hosting required | No                                                    | No (GitHub CLI optional)    | Usually yes                                          |
+
+### Frequently asked comparisons
+
+#### Is Astro Visual Editor a CMS?
+
+No. A CMS stores content in its own records (a database or managed content
+files) and your site queries it. Astro Visual Editor has no content store at
+all: it edits your existing `.astro`, Markdown, JSON and YAML source files in
+place, with every change reviewable as an ordinary Git diff. If you want a
+hosted editing workflow for non-technical users today, a CMS is still the
+right tool — the two can coexist in the same project.
+
+#### How is this different from Stacki?
+
+[Stacki](https://github.com/flowtricks/stacki) is a free, open-source desktop
+app that opens an Astro project and edits it through a component/props
+palette. Astro Visual Editor pursues the same goal — visually edit real Astro
+source with no CMS backend — but runs inside Astro's own Dev Toolbar in the
+browser, so you click and type on the actual rendered page rather than
+working in a separate app. Stacki has a style panel today; this package edits
+any unannotated page with zero setup and reviews every change as a validated
+batch before writing.
+
+#### Do I still need Sanity, Netlify Visual Editor or TinaCMS?
+
+Those tools give hosted, authenticated editing of CMS-managed content with a
+live preview — the right choice when non-technical editors need to publish
+from a browser without a local dev server. Astro Visual Editor solves the
+other half: editing the source files themselves during local development,
+with no accounts, schemas or migration. Many teams would use one of each.
+
+#### How is this different from Keystatic, Sitepins, Decap or Sveltia?
+
+Those are Git-based content editors: a separate admin UI that reads and
+writes Markdown/JSON/YAML content files (usually `src/content/`), commit by
+commit. They never touch `.astro` files and never show you the rendered page
+while you edit. Astro Visual Editor edits on the rendered page itself and
+writes to any supported source file that owns the value, including `.astro`
+component markup.
+
+#### Does it work on a deployed production site?
+
+Not yet, by design: the editor and its write endpoint exist only during
+`astro dev` and are excluded from production builds entirely. An
+authenticated, Git-API-backed deployed mode is on the
+[roadmap](#roadmap-and-requests).
+
+#### Does it work on my existing Astro site without changes?
+
+On conventional pages, yes — enable the editor and unique literal text
+becomes editable immediately, with safe structural matches becoming
+drag-reorderable sections. Pages that compose content from many sources can
+add annotations or mappings to extend coverage; nothing is ever guessed, and
+unprovable edits are refused rather than written.
+
 ## Roadmap and requests
 
 Zero-step editing covers conventional Astro pages today. Planned for the
 next betas, roughly in order:
 
+- **Full design control** — Elementor/Divi-grade style editing rather than
+  today's read-only Design tab: typography (family, size, weight, line
+  height), spacing, colours, backgrounds, borders and shadows, edited on the
+  canvas and written back only where the owning CSS or Astro style source
+  can be proven safely. The nearest open-source peer (Stacki) already ships
+  a style panel; closing this gap is the top priority.
+- **Typed component insertion** — a form-driven way to add a whole component
+  instance and configure its typed props (in the spirit of reading a
+  component's declared prop types and generating matching form fields),
+  alongside today's literal-text and structured-path editing.
 - **Dynamic and collection routes** — inferring the owning content file for
   `[slug]` pages and Content Collections without any mapping.
 - **Repeated-text disambiguation** — safe automatic resolution when the same
   string appears in several files (i18n locales, repeated CTAs).
 - **Client islands** — mapping text rendered by React/Vue/Svelte islands back
   to their component source.
-- **Full design control** — Elementor/Divi-grade style editing rather than
-  today's read-only Design tab: typography (family, size, weight, line
-  height), spacing, colours, backgrounds, borders and shadows, edited on the
-  canvas and written back only where the owning CSS or Astro style source
-  can be proven safely.
 - **Light and dark mode** — theme switching for the editor panel, plus
   light/dark variants in the bundled demos and planned starter themes.
 - **Structured data** — schema.org/JSON-LD editing alongside the existing SEO
@@ -181,6 +272,9 @@ next betas, roughly in order:
   HMR introduces new content mid-session.
 - **Images and assets** — replacing images from the canvas with source-safe
   asset handling.
+- **Client-accessible deployed editing** — an authenticated, SSR-hosted mode
+  that writes through the Git provider API instead of the local filesystem,
+  for non-technical editors on a deployed site rather than only `npm run dev`.
 
 Want one of these sooner, or something we have not planned?
 

packages/astro-visual-editor/README.md

@@ -46,6 +46,11 @@ on the selected block, persistent lock chips on locked content:
 
 ![The visual builder with a selected block toolbar, a locked chip and the docked inspector](https://raw.githubusercontent.com/OpaceDigitalAgency/astro-visual-editor/main/.github/assets/shot-builder.png)
 
+The Page structure navigator — every group, section, row and block,
+Elementor-style, with click-to-select and drag or move-control reordering:
+
+![The Page structure navigator tree showing nested groups, sections, rows and blocks with a selected paragraph highlighted on the canvas](https://raw.githubusercontent.com/OpaceDigitalAgency/astro-visual-editor/main/.github/assets/shot-navigator.png)
+
 The SEO form with all seven fields capability-checked against their real
 source, and the review tray where every change waits for one validated save:
 
@@ -60,22 +65,44 @@ multi-file batch) and **Plain (zero setup)** (an unannotated page edited
 entirely by inference). The demo also bundles `@astrojs/sitemap` and real
 head markup so SEO editing is proven against a conventional Astro site.
 
+## How this compares
+
+Most "Astro CMS" tools (Keystatic, Sitepins, Writenex, Sveltia, Sanity,
+Netlify Visual Editor, TinaCMS) edit structured content records through a
+separate admin UI or hosted studio, not `.astro` source. The closest actual
+peer is [Stacki](https://github.com/flowtricks/stacki), a free open-source
+desktop app that also edits Astro projects locally with no CMS backend, via
+a component/props palette rather than click-any-text editing inside the Dev
+Toolbar. Stacki already ships a style panel this package does not yet have —
+see Roadmap below. Full comparison in the
+[repository README](https://github.com/OpaceDigitalAgency/astro-visual-editor#how-this-compares).
+
+**Is it a CMS?** No — there is no content store. It edits your existing
+`.astro`, Markdown, JSON and YAML source files in place, reviewable as an
+ordinary Git diff, and can coexist with any CMS. **Do I still need Sanity,
+Netlify Visual Editor or TinaCMS?** Those provide hosted editing of
+CMS-managed content for non-technical publishers; this edits the source
+itself during local development. Many teams would use one of each. More
+comparisons (Stacki, Keystatic, Sitepins, Decap, Sveltia) in the
+[repository FAQ](https://github.com/OpaceDigitalAgency/astro-visual-editor#frequently-asked-comparisons).
+
 ## Roadmap and requests
 
 Zero-step editing covers conventional Astro pages today. Planned for the
 next betas, roughly in order:
 
+- **Full design control** — Elementor/Divi-grade style editing rather than
+  today's read-only Design tab. The nearest open-source peer already ships a
+  style panel; closing this gap is the top priority.
+- **Typed component insertion** — a form-driven way to add and configure a
+  whole component instance from its typed props, alongside today's literal-
+  text and structured-path editing.
 - **Dynamic and collection routes** — inferring the owning content file for
   `[slug]` pages and Content Collections without any mapping.
 - **Repeated-text disambiguation** — safe automatic resolution when the same
   string appears in several files (i18n locales, repeated CTAs).
 - **Client islands** — mapping text rendered by React/Vue/Svelte islands back
   to their component source.
-- **Full design control** — Elementor/Divi-grade style editing rather than
-  today's read-only Design tab: typography (family, size, weight, line
-  height), spacing, colours, backgrounds, borders and shadows, edited on the
-  canvas and written back only where the owning CSS or Astro style source
-  can be proven safely.
 - **Light and dark mode** — theme switching for the editor panel, plus
   light/dark variants in the bundled demos and planned starter themes.
 - **Structured data** — schema.org/JSON-LD editing alongside the existing SEO
@@ -84,6 +111,9 @@ next betas, roughly in order:
   HMR introduces new content mid-session.
 - **Images and assets** — replacing images from the canvas with source-safe
   asset handling.
+- **Client-accessible deployed editing** — an authenticated, SSR-hosted mode
+  writing through the Git provider API for non-technical editors, not just
+  local `npm run dev`.
 
 Want one of these sooner, or something we have not planned?