Feature: Extract Shell Syntax Explainer as standalone module

[KatsuJinCode]

Summary

The tokenized shell syntax explainer panel in DeClaude could be valuable as a standalone, reusable module that other projects could integrate.

What we have

• Comprehensive tokenization for PowerShell, Bash, Zsh, Fish, Nushell, CMD
• Token dictionary with descriptions for 100+ shell syntax elements
• Interactive hover tooltips explaining each token
• Syntax highlighting with category-based colors
• Line-level highlighting for context

Proposed module features

• Zero dependencies (vanilla JS)
• Easy to embed: <shell-explainer code="..." shell="powershell"></shell-explainer>
• Customizable themes
• Extensible token dictionary
• Support for custom syntax highlighting

Use cases

• Documentation sites explaining shell commands
• Tutorial platforms teaching shell scripting
• Code review tools
• IDE/editor plugins
• Educational materials

Implementation ideas

• Web Component for easy embedding
• NPM package for Node.js projects
• CDN distribution for quick integration
• Optional: React/Vue/Svelte wrappers

Would this be useful to you?

Comment below if you'd use this as a standalone module, and what features would be most valuable!

[KatsuJinCode]

@codex review and propose complete implementation plan

[chatgpt-codex-connector]

Below is a comprehensive implementation plan to extract the existing shell syntax explainer into a standalone, reusable module.

1. Clarify current explainer responsibilities and separation boundaries (UI toggles, token parsing, tooltip rendering, styling hooks)

• The explain-mode toggle and expertise-level behaviors live in js/ui.js, and the token rendering/parsing/line-highlighting logic plus the token dictionary live in js/utils.js. js/ui.jsL64-L110 js/ui.jsL421-L470 js/utils.jsL230-L326 js/utils.jsL386-L440
  :::task-stub{title="Audit current explainer responsibilities and API surface"}
• Map all explainer entry points (e.g., toggleExplainMode, parseCommandTokens, tooltip positioning) in js/ui.js and js/utils.js.
• Document the minimum inputs needed (code string, shell type, token dictionary overrides, theme hooks) and outputs (DOM, events).
• Decide which parts become the public API vs. internal helpers for the standalone module.
  :::

2. Extract core parsing + rendering into a standalone web component (vanilla JS, zero deps)

• Move tokenization/rendering into a self-contained class/custom element, parameterized by code, shell, and optional config (dictionary overrides, line highlighting, expertise level). Reuse existing parsing logic and tooltip generation from js/utils.js. js/utils.jsL230-L326 js/utils.jsL386-L440
  :::task-stub{title="Create <shell-explainer> web component"}
• Add a new module file (e.g., web-component/shell-explainer.js) that defines a custom element wrapping the parsing/rendering flow from js/utils.js.
• Accept attributes/props: code, shell, highlight-profile, expertise, theme, dictionary.
• Implement lifecycle callbacks to render on connect/attribute change and to clean up listeners.
• Expose an imperative API (e.g., setCode, setShell, setDictionary) for integrators.
  :::

3. Modularize token dictionary and extensibility hooks

• Current dictionary is a single object; split per-shell dictionaries and allow merges/overrides, with fallback to defaults. js/utils.jsL386-L440
  :::task-stub{title="Refactor token dictionary into modular, override-friendly structure"}
• Extract the dictionary into separate files per shell (e.g., tokens/powershell.js, tokens/bash.js, etc.).
• Provide a mergeDictionary(base, overrides) helper to support custom tokens.
• Update the web component to accept an override dictionary and compose it with the defaults for the selected shell.
  :::

4. Theming and styling surface

• Current styles live in css/theme.css/css/layout.css for the app; expose CSS variables and minimal default styles for embedding. (Styles referenced by .command-token, .token-tooltip, .explain-line.) css/theme.cssL1-L120
  :::task-stub{title="Define portable styling with CSS variables"}
• Create a dedicated stylesheet (e.g., web-component/shell-explainer.css) containing the necessary classes with CSS variables for colors, spacing, and typography.
• Document the variables and provide a light/dark theme example.
• Ensure the component scopes styles to its shadow DOM, while allowing host overrides via CSS variables.
  :::

5. Build and distribution pipeline

• Need NPM package + CDN bundle (vanilla, zero external deps).
  :::task-stub{title="Set up packaging and builds"}
• Add a minimal build step (e.g., Rollup/Vite) to emit ESM (shell-explainer.esm.js) and IIFE (shell-explainer.min.js) bundles plus CSS.
• Configure package.json with exports, types (if adding TS typings), and files for distribution.
• Add a simple npm publish --dry-run check and versioning docs.
  :::

6. Integration back into DeClaude app (use the component internally)

• Replace the in-app explain panel with the new component to ensure dogfooding and backward compatibility with existing controls (expertise toggle, highlight behaviors). js/ui.jsL64-L110 js/ui.jsL421-L470
  :::task-stub{title="Adopt web component inside existing DeClaude UI"}
• Mount <shell-explainer> in the current explain panel container, wiring code, shell, and highlight props from existing state.
• Remove or thin any duplicated rendering logic left in js/utils.js.
• Validate that expertise-level toggles still map to component props (e.g., tooltip verbosity, risk labels).
  :::

7. API docs, examples, and demo page

• Provide embedding examples for plain HTML, React/Vue/Svelte wrappers (optional), and CDN usage.
  :::task-stub{title="Document and demo the standalone module"}
• Add README section (or docs/standalone.md) covering installation, attributes/props, CSS variables, dictionary overrides, and events.
• Create a lightweight demo page under examples/ that loads the component via CDN build and showcases theming + custom tokens.
• If wrappers are provided, include minimal usage snippets for each framework.
  :::

8. Testing and validation

• Need unit tests for token parsing/rendering and visual regression/screenshot checks for tooltips/highlighting.
  :::task-stub{title="Add tests for parsing and rendering"}
• Set up a test runner (e.g., Vitest/Jest + jsdom) for the component’s parsing/rendering output.
• Add fixture-based tests per shell to ensure tokens and tooltips render correctly with overrides.
• Add a minimal Playwright script (if supported) to capture screenshots of the component for default and themed states.
  :::

9. Release and migration notes

• Communicate migration from internal logic to the reusable module for current users.
  :::task-stub{title="Prepare release notes and migration guidance"}
• Draft a changelog entry describing the new package, API, and how the app now consumes it.
• Note any breaking changes (e.g., renamed CSS classes or required props) and provide upgrade steps.
• Outline versioning/maintenance expectations for future syntax expansions.
  :::

If you want me to adjust scope (e.g., omit framework wrappers or skip CDN build), I can refine the plan accordingly.

View task →