Repository navigation
feat: add plz-explain with 2D and 3D stage kits and retire plz-3d-explain - #45
Open
codekongdev wants to merge 8 commits into
Open
codekongdev wants to merge 8 commits into
codekongdev wants to merge 8 commits into
Conversation
Split the explainer page into a kit-agnostic shell and stage kits. The existing three.js block model becomes the first kit (axo), loaded only when a scene uses it. Shell features: speed split button, draggable text/stage divider, auto-play, stage caption rail with step badges, and a director that keeps step order under reduced motion. Move defaults to 1000 ms. Add the skill docs, Korean and English sandbox examples, shell browser tests, and a shared browser harness for the browser test suites.
Add a second stage kit for row-level step diagrams: tables with row states, hash buckets, filter gates, operator boxes with counters, connectors, travelling tokens, side-by-side panels, operator trees and node columns. Pages with only svg scenes do not load three.js, and a page can mix axo and svg chapters. The diagram scales up to 1.6x on large stages and adapts row heights on phones. Frames are sized from measured text, and clipped() reports text wider than its frame. Make the browser tests load-independent: assert the director's own timeline instead of wall-clock ratios, wait for kits to settle before sampling, and share helpers through browser-harness.mjs.
Add a five-chapter svg-kit example in Korean and English: plan tree, build and probe, the SIP filter, filter off vs on, and a network step the filter cannot cross. It loads no three.js. Extend the svg kit for it: tree edges for travelling chips, tokens sized to their text with resting points that keep them inside their frame, key-only tables, narrow boxes, panels that sit side by side when they fit, column edge points, and optional headers and gate chips. clipped() now also reports text taller than its frame, tokens leaving their container, and text covered by a pill or chip.
Give each kit its own delimited css and js section in the template, so a generated page carries the shell plus only the kits it uses. The examples now ship one kit each. check-templates compares each kit section verbatim and checks its position and the stage's data-kits. data-kits is authoritative: a page stops with a readable [plz] message when a scene uses a kit that is not listed, or lists one it does not use. Kit setup outside scenes moves into setupKit(). The intro note follows the kits on the page and never falls back to English on pages in other languages. Run the test files one at a time with npm test, which CI now uses, so the browser suites no longer starve each other.
Add time-axis lanes to the svg kit: one column per actor with time running down, a resource lane between them, events, messages that follow the playhead, waiting and lock spans, and a.play() to advance the playhead step by step. Add a five-chapter example in Korean and English on the lost update anomaly, row locks and version checks, following PostgreSQL 18 at Read Committed. Measure text through one estimator across the kit, and make size() agree with place() when lanes switch to their short texts.
Let a scene declare 1-3 slider parameters and presets. The stage redraws on input, the run button plays an authored tour, and the reader explores afterwards. Add chart, meter, readout and bit-array parts. Reader input always wins over auto-play: any press, key or value change stops the tour and holds auto-play for a grace period, without relying on focus, and values the reader set stay until they run the chapter or leave it. Add a five-chapter Bloom filter example in Korean and English. Its numbers are computed by the page and checked against independent values in the tests.
Add a code panel with a current-line marker and run traces, plus call stack, queue, console and variable parts. a.line() moves the marker and marks a step; scenes can offer a Step button so the reader predicts before each step, and Run continues a stepped run to the end. Add a five-chapter JavaScript event loop example in Korean and English. Each program's console order is checked against a real run in the browser. Measure the reading line from the current layout on scroll instead of an observer rebuilt on stage resize, so stacked chapters with different stage heights no longer flip back and forth. d.flow now wraps parts into rows on wide stages.
Add a per-chapter form selection procedure to SKILL.md, with a forms catalog and motion rules in references/forms.md and motion.md. A trial with two unseen topics shaped the tie-break rules. Add the plz-explain README in four languages with demo screenshots, and make plz-explain the featured skill in the root README. Retire plz-3d-explain: no trigger phrases, a pointer to plz-explain, and a fallback for installs without plz-explain. It will be removed in a later release. The svg kit now compares wrappings of d.flow by scale, keeps the captions-right preference across them, centres the block, and reserves caption room from the chapter's real captions so none scrolls away.
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
This branch has not been deployed
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
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.
Summary
Adds plz-explain, a new skill that builds interactive study pages where each chapter picks the visual form that fits what it teaches, and retires plz-3d-explain in its favour.
plz-3d-explain drew every chapter as a 3D block model. That fits layers and isolation, but not topics whose information lives in values and order (joins, filters, transactions). plz-explain splits the page into a kit-agnostic shell and stage kits:
axokit: the existing three.js block model, loaded only when a page uses it.svgkit: 2D diagrams with eight forms in total: step diagram, operator tree, side-by-side panels, node columns, time-axis lanes, parameter playground (sliders and charts), and code-and-state with a Step button.references/forms.md) and motion rules with sources (references/motion.md).npm test(node --test --test-concurrency=1 scripts/*.test.mjs) runs the files one at a time, because the browser suites starve each other in parallel. CI uses it.check-templates.mjsnow checks kit sections anddata-kits.Type of change
SKILL.md,references/, orassets/)How I verified it
node scripts/check-readme-translations.mjsandnode scripts/check-templates.mjspass.npm test: 321/321 on the final commit before rebasing onto main (about 9.5 minutes).overlaps()andclipped()empty, auto-play loops, reduced motion, no three.js request on svg-only pages, no Hangul on English pages.Checklist
node scripts/check-readme-translations.mjspasses (or I only changed things it does not cover)ENGINEintemplate.html, I applied the same change toexample-agent-sandbox.html, andnode scripts/check-templates.mjspassesUI_TEXTkey, I added it foren,ko,ja, andzh-CN, andnode scripts/check-templates.mjspassesreferences/preferences.md, generated pages, or verification screenshotsNew external URLs are the sources cited on the example pages and in
references/forms.md, and GitHub Pages demo links for the new examples. The README addsnpx skills add codekongdev/plz --skill plz-explainandnpx skills remove plz-3d-explain -gto the install instructions.