Skip to content

feat: add plz-explain with 2D and 3D stage kits and retire plz-3d-explain - #45

Open
codekongdev wants to merge 8 commits into
mainfrom
feat/plz-explain
Open

codekongdev wants to merge 8 commits into
mainfrom
feat/plz-explain

Conversation

@codekongdev

Copy link
Copy Markdown
Owner

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:

  • Shell: chapters and scroll sync, a speed menu on the run button, a draggable text/stage divider, auto-play, a caption rail on the stage with step badges, and a director that keeps step order under reduced motion.
  • axo kit: the existing three.js block model, loaded only when a page uses it.
  • svg kit: 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.
  • Form selection: SKILL.md now has a per-chapter procedure, with a forms catalog (references/forms.md) and motion rules with sources (references/motion.md).
  • Examples (Korean and English): agent sandbox (3D), hash join and SIP, lost update, Bloom filter, JavaScript event loop. Facts in the new examples were checked against primary sources, listed on each page; the event loop page's console orders are checked against a real run in the tests.
  • Retiring 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.
  • Tests: 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.mjs now checks kit sections and data-kits.

Type of change

  • Translation or README
  • Bug fix
  • Skill improvement (SKILL.md, references/, or assets/)
  • New skill
  • CI or tooling
  • Other

How I verified it

  • node scripts/check-readme-translations.mjs and node scripts/check-templates.mjs pass.
  • npm test: 321/321 on the final commit before rebasing onto main (about 9.5 minutes).
  • Browser validation of every example: every chapter at 1440×900 (divider at minimum, default and maximum), 2282×1293, 390×844, 360×800 and 844×390 with overlaps() and clipped() empty, auto-play loops, reduced motion, no three.js request on svg-only pages, no Hangul on English pages.
  • Each phase was code-reviewed and the findings fixed before commit.
  • Not covered: the suites run Chromium only. Slider and Step interaction were not tried in real Safari or Firefox.

Checklist

  • node scripts/check-readme-translations.mjs passes (or I only changed things it does not cover)
  • If I changed ENGINE in template.html, I applied the same change to example-agent-sandbox.html, and node scripts/check-templates.mjs passes
  • If I added a UI_TEXT key, I added it for en, ko, ja, and zh-CN, and node scripts/check-templates.mjs passes
  • I did not commit references/preferences.md, generated pages, or verification screenshots
  • I added no new external URLs or shell commands, or I explained them in the summary above
  • If this is a new skill, I understand that maintainers may add the translations to my branch, and I enabled "Allow edits by maintainers"

New 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 adds npx skills add codekongdev/plz --skill plz-explain and npx skills remove plz-3d-explain -g to the install instructions.

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.
@coderabbitai

coderabbitai Bot commented Nov 20, 2026

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant