docs: surface pointer + trace playgrounds into a top-level Explore section#227
Open
gnidan wants to merge 11 commits into
Open
docs: surface pointer + trace playgrounds into a top-level Explore section#227gnidan wants to merge 11 commits into
gnidan wants to merge 11 commits into
Conversation
Contributor
|
gnidan
added a commit
that referenced
this pull request
Jul 3, 2026
Per gnidan #227 review: Explore now sits after Reference (position 8) instead of position 2.
gnidan
added a commit
that referenced
this pull request
Jul 3, 2026
- pointer-playground: mark "pointer" as an ethdebug/format noun (bold+link to the pointers reference) - bug-playground: introduce BUG + bugc (optimizing reference compiler) and the self-referential validation angle - Explore CTA sidebar_labels (drop "Playground"): per-item call-to-action wording
gnidan
added a commit
that referenced
this pull request
Jul 3, 2026
#243) The docs BugPlayground only ever showed one program; the example picker lived in the standalone packages/playground app. Port a lean version into the docs widget (gnidan #33). - bugc-react: add a curated `bugExamples` set (Counter, Function calls, Arrays & loops) as a reusable export. Sources are distilled from packages/bugc/examples and stripped of the `/*@test*/` behavioral annotations the raw files carry, so they read cleanly in an editor. examples.test.ts asserts each compiles to bytecode without errors (guards against a typo in an inlined source); adds the missing vitest.config.ts so the package's test script runs. - web BugPlayground: add an optional `examples` prop (defaults to bugExamples) and an Example dropdown in the header controls. The selector shows only when no `initialCode` is passed — so the bare playground page gains it while inline single-example doc embeds stay unchanged. Selecting an example loads its source and recompiles. Additive; does not affect the tracer or #227. Example sources verified to compile via the new tests; UI wiring mirrors the existing optimizer selector.
gnidan
force-pushed
the
transform-context
branch
from
883d0f5 to
94a800e
Compare
gnidan
added a commit
that referenced
this pull request
Jul 10, 2026
#243) The docs BugPlayground only ever showed one program; the example picker lived in the standalone packages/playground app. Port a lean version into the docs widget (gnidan #33). - bugc-react: add a curated `bugExamples` set (Counter, Function calls, Arrays & loops) as a reusable export. Sources are distilled from packages/bugc/examples and stripped of the `/*@test*/` behavioral annotations the raw files carry, so they read cleanly in an editor. examples.test.ts asserts each compiles to bytecode without errors (guards against a typo in an inlined source); adds the missing vitest.config.ts so the package's test script runs. - web BugPlayground: add an optional `examples` prop (defaults to bugExamples) and an Example dropdown in the header controls. The selector shows only when no `initialCode` is passed — so the bare playground page gains it while inline single-example doc embeds stay unchanged. Selecting an example loads its source and recompiles. Additive; does not affect the tracer or #227. Example sources verified to compile via the new tests; UI wiring mirrors the existing optimizer selector.
gnidan
force-pushed
the
docs-explore-section
branch
from
962b0b6 to
7296cf9
Compare
gnidan
added a commit
that referenced
this pull request
Jul 10, 2026
Per gnidan #227 review: Explore now sits after Reference (position 8) instead of position 2.
gnidan
added a commit
that referenced
this pull request
Jul 10, 2026
- pointer-playground: mark "pointer" as an ethdebug/format noun (bold+link to the pointers reference) - bug-playground: introduce BUG + bugc (optimizing reference compiler) and the self-referential validation angle - Explore CTA sidebar_labels (drop "Playground"): per-item call-to-action wording
Content for the docs reorg (#17), authored for integration into docs' Explore section (docs/explore/, per gnidan's Option A + build-fresh-and- trim). Authoring source for docs to integrate onto docs-explore-section. - explore/trace-playground.mdx: learn-by-doing (counter -> function call -> tail-call optimization). - explore/pointer-playground.mdx: curated cross-topic (memory region, storage slot, struct group, computed-slot expression). - explore/index.mdx: Explore hub linking the three playgrounds. - explore/bug-playground.mdx: moved from examples/. - core-schemas/programs/tracing.mdx: trimmed to reference; interactive examples moved to the Trace playground. - implementation-guides/building-a-trace-viewer.mdx: extracted how-to. - pointers/{regions,collections,expressions}.mdx: interactive examples removed, schema tables + prose kept, playground cross-links added. All internal links point at /docs/explore/*.
Structural wiring to complete the Explore section reorg: - add explore/_category_.json (label "Explore", sidebar position 2) - add navbar "Playground" item -> /docs/explore - renumber subsequent categories (Getting started 3, Concepts 4, Core schemas 5, Implementation guides 6; Reference 7) - order Explore pages: Pointer / Trace / BUG playground per plan - repoint former /docs/examples links (overview, getting-started, compiler guides) to /docs/explore and drop the stale resources pagination override Composes with the Explore content + reference trims. Part of #17.
Per review: remove the top-nav Playground entry so the header reads Documentation | Specification. The Explore sidebar section (the core reorg) stays. Part of #17.
explore/index.mdx carried pagination_prev: core-schemas/info/resources from the old examples/ page (position 6). With Explore now at position 2, that pointed Previous forward into Core schemas; drop it so Previous auto-links to Project overview. Part of #17.
Per review, replace the toy pointer examples with real Solidity storage layouts: packed sub-slot address, dynamic array element (keccak256(5)+i), mapping value (keccak256(key,3)), and the flagship short/long storage string (one pointer resolved against both short and long state). Content authored by writer; keeps sidebar_position 2 (Pointer/Trace/BUG). #17.
lint-staged's glob skips .mdx, so the rebuilt examples slipped past the local hook; apply prettier (quote-style only). #17
Per gnidan #227 review: Explore now sits after Reference (position 8) instead of position 2.
- pointer-playground: mark "pointer" as an ethdebug/format noun (bold+link to the pointers reference) - bug-playground: introduce BUG + bugc (optimizing reference compiler) and the self-referential validation angle - Explore CTA sidebar_labels (drop "Playground"): per-item call-to-action wording
- core-schemas/pointers/index.mdx: mark "pointer"/"ethdebug/format" as nouns on first use (harmonizes with the Explore pointer intro) - trace CTA sidebar_label: drop "live"
The Explore reorg was authored on top of transform-context, so a few pages referenced compiler-transform features (tailcall transform, the O0/O2 optimizer selector, the transform context spec) that don't exist on main. Landing #227 independently on main, strip those: - tracing.mdx: remove the "Optimized code: the tailcall transform" section (linked /spec/program/context/transform — a 404 on main). - trace-playground.mdx: remove the "Watching the optimizer" section and its tailRecursiveSum/tailRecursiveFactorial imports (not exported by main's tracing-examples.ts). Keep the Counter and function-call examples, which work on main. - explore/index.mdx: drop the dangling "tail-call transform" clause.
gnidan
force-pushed
the
docs-explore-section
branch
from
7296cf9 to
3844669
Compare
Drop the lowercase descriptive-CTA sidebar_label overrides on the three playground pages so the sidebar falls back to each page's H1 — Pointer playground, Trace playground, BUG playground. Matches the sentence-case short-noun convention used across the rest of the sidebar (Overview, The dereference function, etc.).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Surfaces the interactive pointer and trace playgrounds out of the dense Core
Schemas reference and into a dedicated top-level Explore section — the
project's best teaching material, previously buried under reference/spec pages.
This is a
packages/web(docs site) change only — no spec or schema changes.Structure
Pointer Playground, Trace Playground, BUG Playground, plus a hub landing
page.
now-empty Examples category is removed.
/docs/examples/*links (overview, getting-started,compiler guides) to
/docs/explore/*and drops a stale pagination override.Content
(pointers: memory slice / storage slot / struct group / computed slot;
tracing: counter → function call).
(regions / collections / expressions / tracing), keeping the schema tables,
static SchemaExamples, and spec links, with cross-links to the playgrounds.
Scope
Targets
mainindependently of the in-flight transform-context work. Thereorg was originally authored on top of transform-context, so a few pages
referenced compiler-transform features that don't exist on
mainyet — thetailcall transform, the O0/O2 optimizer selector, and the
/spec/program/context/transformpage. Those sections are intentionallyexcluded here (last commit) so the section stands on its own on
main; theyget re-homed onto transform-context in this same Explore IA once it lands.
That's why the Trace Playground ships two examples (storage write, function
call) rather than the optimizer walkthrough.
Prose authored by writer; structural wiring by docs.
Note: the old
/docs/examples/*URLs change to/docs/explore/*. All in-repolinks are updated; a client-side redirect for external inbound links is a
possible follow-up (needs the plugin-client-redirects dependency).