Docs: landing scope memo, deployment record, VS Code extension exploration

docs/exploration/landing-onboarding-scope.md

@@ -0,0 +1,177 @@
+# Landing & Onboarding Scope
+
+_Point-in-time scope memo, 2026-07-04. Consolidates the onboarding/landing review: audience
+model, claims audit, objection map, target landing architecture, and the implementation
+phases. Supersedes nothing; feeds the next landing/onboarding sessions._
+
+_Status (2026-07-04, same session): **Phases 1 and 2 shipped** — deep links, paste door,
+learn links, brushed-scatter example, and the full landing overhaul (showcase block,
+editor proof, objection beats, reweighted blocks, trust creed, voice pass). Phase 3
+(learn growth) remains. Gotcha recorded at the code site: faceted/concat specs need
+`fitMode: 'default'` in `LandingChart` — the width-fit contract can't size their
+children._
+
+## Audience & thesis
+
+The goal of the public surfaces is to **popularize Vega-Lite's capabilities**, not to serve
+a niche. Two audiences, one page, two pitches:
+
+- **Beginners / the declarative-curious** — sold on **Vega-Lite itself**: charts written as
+  text, interactive by declaration, beautiful out of the box (something users rarely have
+  time to achieve themselves). Their doors: the Chart Builder, examples, `/learn/`.
+- **Practitioners** (already write specs, often via wrappers) — sold on **the editor**: a
+  home for specs (vs. the Vega editor's scratchpad), schema-aware Monaco, dataset library,
+  themes/fonts, export parameters the vega-embed kebab menu never offers.
+
+The surface stays **general-purpose**: learners are welcome underneath, but nothing reads
+as a teaching tool or classroom product. Blocks alternate between the two pitches; the
+strongest moves serve both at once (a themed, interactive chart sells VL capability to the
+beginner and the theming machinery to the practitioner in the same pixels).
+
+Hero-copy consequence: "A home for your Vega-Lite charts" addresses only people who
+already have Vega-Lite charts. The headline must admit the beginner too — positive case
+first (charts as text: interactive, themeable, durable), "home for them" as the second
+beat.
+
+## Claims audit (2026-07-04)
+
+Every claim on the current landing verifies against the code — no overclaims. The page
+**underclaims**: shipped capabilities absent from it, in order of missed leverage:
+
+1. **Interactivity** — the page contains zero interactive charts (live-rendered, yes;
+   interactive, no), while interactivity is VL's headline capability for popularization.
+2. **Composition wireframe** — drag-editable multi-view editing; unique in the Vega
+   ecosystem; unmentioned.
+3. **Data inspector** — input vs. resolved rows per view; the answer to "why is my chart
+   empty"; unmentioned.
+4. **CodeLens scaffolds** — one-click working params/transforms/view blocks; the bridge
+   feature (beginners get working code to study, practitioners get speed); unmentioned.
+5. **Theme Builder breadth** — landing lists colour/type/axes/legend/layout; it also does
+   marks, titles, number formats.
+6. **`/learn/`** — a capability, currently only a nav link.
+
+Nitpick: "Sixteen presets" counts "Stock Vega-Lite (no theme)" as a preset.
+
+Page-wide visual finding: nearly every chart renders in default blue. The page's imagery
+_is_ its charts; they must carry themed variety — the page itself is the proof of
+"out-of-the-box beauty without the time investment".
+
+Pacing findings (desktop 1440, light): theme block ≈ a quarter of total scroll (three
+tall charts stacked); builder demo's default state is the most boring chart it can produce
+(count-by-channel, plain blue); datasets — the core "home, not scratchpad" argument — gets
+the weakest visual (small static mock); export gets a full peer block for what is partly
+table-stakes; the hero app window reads as a screenshot (nothing signals it is live).
+
+## Objection map
+
+Objections cluster two ways; each gets **one compact moment** on the page, not a FAQ
+sprawl. The best answers are either **on-ramps** or **stances stated before suspicion
+forms**.
+
+**Habit cluster** — "I already have a way" — one positioning block near the editor
+section:
+
+- _Vega editor?_ A scratchpad, not a home. (One-slot, no library, no fonts/themes.)
+- _Altair / wrappers?_ Their output **is** a Vega-Lite spec — paste it in, polish, keep.
+  Most real-world VL usage is via Altair; this is the largest single objection. Nobody
+  hand-writes specs from a blank buffer, and Astrolabe never asks them to (examples,
+  builder, paste + autocomplete/scaffolds/inspector). Last-mile polish (label exprs, axis
+  formats) is often faster in the spec than translated back through a wrapper API.
+- _LLMs write specs?_ Yes — paste it here; this is where an almost-right spec gets
+  diagnosed (preview, validation, inspector). AI-free is a privacy feature: the model
+  never sees the real data.
+
+**Trust cluster** — generated by the local-only stance itself — lives at/near the creed:
+
+- _Local = fragile?_ The library exports as one JSON file; back it up like any file you
+  own. Copy must stay on export/import — never imply sync (none exists).
+- _Closed source, so why believe "no data leaves"?_ Falsifiable claim instead: static
+  site, no backend, works fully offline once installed — airplane mode is the audit.
+  (Never claim open source.)
+- _Solo project longevity?_ Lock-in-free is the honest answer: everything is ordinary
+  Vega-Lite JSON; specs outlive the tool; the PWA keeps working offline.
+- _Sharing?_ Exports are the sharing story; spec-with-data-inlined is quietly the share
+  feature and should be framed as one.
+
+Beginner-adjacent beat (one line, no comparison table): vs. Datawrapper/Flourish — no
+account, no hosting dependency, real interactivity, a growing library you own.
+
+**Deliberately not addressed on the landing**: storage limits / huge datasets (real
+constraint, edge concern; the in-app storage monitor is the right surface — raising it in
+marketing plants a worry most visitors never had).
+
+## Target landing architecture
+
+1. **Hero + app window** — dual-audience headline; default example themed and
+   interactive; explicit "this is the real app — try it" affordance; window's snippets
+   deep-link into the app.
+2. **"What Vega-Lite can do"** — NEW, the popularization centerpiece: 2–3 interactive
+   charts (tooltip; brush → linked filter; a facet) in distinct themes, each beside its
+   short spec. Argument: _this is a text file._
+3. **"A serious editor"** — practitioner proof: autocomplete/validation/inline docs
+   shown (staged, NOT real Monaco — the post-build gate keeps Monaco off the landing),
+   CodeLens scaffold shown, data inspector named. Positioning block (habit cluster)
+   attaches here.
+4. **"Don't want to start from JSON?"** — builder, explicitly the second door; demo
+   defaults to a colourful non-trivial state (an intent applied, colour encoding on).
+5. **"One library"** — datasets promoted and made vivid (extract-inline-data
+   before/after is the honest demo).
+6. **"Make it yours"** — half current height: one chart + theme switcher, gallery as a
+   compact grid, fonts in the first sentence.
+7. **"Get it out the way you need it"** — export reframed as practitioner pain relief
+   (parameters the vega-embed kebab menu lacks), compact; inline-data export framed as
+   sharing.
+8. **Creed** — plus the trust cluster (backup/export, offline-as-proof, portability-as-
+   longevity) → learn pointer → close.
+
+Verify on mobile and dark before committing layout.
+
+## App-side changes
+
+- **Deep links in**: `#build` already exists in the hash grammar — the landing builder
+  demo can link today. Add `#example-<id>` (consumed once at startup: create that
+  example as a snippet, open it, clear the param) so landing demos hand off momentum
+  instead of resetting at the onboarding canvas. Spec §01 hash table updates with it.
+- **Onboarding canvas third door — "Paste a spec"**: serves Altair users, LLM users,
+  Vega-editor migrants; today they must Create → select-all → delete → paste. Also a
+  quiet "Restoring from an export? Import your workspace" line (Import is header-icon-only
+  during onboarding). Spec §02 updates.
+- **Example gallery showpieces**: add 1–2 interactive/composed examples (brushable
+  scatter + linked histogram; ties to the existing linked-views lesson). Single source of
+  truth pays twice: the landing hero window shows them automatically.
+- **Learn wiring**: the app currently has zero links to `/learn/`. Add: About modal, and
+  a low-key onboarding-canvas line.
+
+## Learn direction
+
+- Lessons gain "Open in Astrolabe" (mechanism: example ids where possible; arbitrary
+  stage specs need a spec-payload deep link — decide at implementation, watch hash size).
+- Content growth (later): lessons keyed to examples ("what to try next with the
+  scatter"), draft/publish workflow, theming walkthrough. Until grown, keep nav billing
+  consistent with a two-lesson section.
+
+## Implementation phases
+
+**Phase 1 — connective tissue (app-side, one session):**
+`#example-<id>` deep link (core parse + startup consumption + tests) · paste-a-spec door
+(+ import line) on the onboarding canvas · learn links (About + canvas) · showpiece
+example(s) in `CHART_EXAMPLES` with compile test · spec §01/§02 updates in-session.
+
+**Phase 2 — landing overhaul (design-involved):**
+New showcase block (#2) first — it is the thesis · editor-proof block (#3, staged
+visuals, no Monaco import) · resequence/reweight (#4–#7) · hero copy + live-affordance ·
+objection + trust beats · themed-chart pass across every chart on the page · mobile/dark
+pass.
+
+**Phase 3 — learn growth (ongoing content):**
+"Open in Astrolabe" from lessons · new lessons per the direction above.
+
+## Parked / deferred
+
+- Post-first-snippet discoverability (draft/publish, extract, theming are invisible until
+  stumbled on; no tours — against the app's grain) → parked in `docs/ux-second-pass.md`
+  for the batched council pass.
+- Multi-device sync → separate exploration (see monetization/sync memo); landing copy
+  must not imply it.
+- URL-encoded spec sharing (à la Vega editor) → plausible future feature if the sharing
+  objection keeps surfacing; product, not copy.