npm - bitwrench - Versions diffs - 2.0.22 → 2.0.23 - Mend

bitwrench 2.0.22 → 2.0.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (88) hide show

package/LICENSE.txt +1 -1
package/README.md +4 -3
package/bin/bwmcp.js +3 -0
package/dist/bitwrench-bccl.cjs.js +1 -1
package/dist/bitwrench-bccl.cjs.min.js +1 -1
package/dist/bitwrench-bccl.cjs.min.js.gz +0 -0
package/dist/bitwrench-bccl.esm.js +1 -1
package/dist/bitwrench-bccl.esm.min.js +1 -1
package/dist/bitwrench-bccl.esm.min.js.gz +0 -0
package/dist/bitwrench-bccl.umd.js +1 -1
package/dist/bitwrench-bccl.umd.min.js +1 -1
package/dist/bitwrench-bccl.umd.min.js.gz +0 -0
package/dist/bitwrench-code-edit.cjs.js +1 -1
package/dist/bitwrench-code-edit.cjs.min.js +1 -1
package/dist/bitwrench-code-edit.es5.js +1 -1
package/dist/bitwrench-code-edit.es5.min.js +1 -1
package/dist/bitwrench-code-edit.esm.js +1 -1
package/dist/bitwrench-code-edit.esm.min.js +1 -1
package/dist/bitwrench-code-edit.umd.js +1 -1
package/dist/bitwrench-code-edit.umd.min.js +1 -1
package/dist/bitwrench-code-edit.umd.min.js.gz +0 -0
package/dist/bitwrench-debug.js +1 -1
package/dist/bitwrench-debug.min.js +1 -1
package/dist/bitwrench-lean.cjs.js +3 -3
package/dist/bitwrench-lean.cjs.min.js +2 -2
package/dist/bitwrench-lean.cjs.min.js.gz +0 -0
package/dist/bitwrench-lean.es5.js +3 -3
package/dist/bitwrench-lean.es5.min.js +2 -2
package/dist/bitwrench-lean.es5.min.js.gz +0 -0
package/dist/bitwrench-lean.esm.js +3 -3
package/dist/bitwrench-lean.esm.min.js +2 -2
package/dist/bitwrench-lean.esm.min.js.gz +0 -0
package/dist/bitwrench-lean.umd.js +3 -3
package/dist/bitwrench-lean.umd.min.js +2 -2
package/dist/bitwrench-lean.umd.min.js.gz +0 -0
package/dist/bitwrench-util-css.cjs.js +1 -1
package/dist/bitwrench-util-css.cjs.min.js +1 -1
package/dist/bitwrench-util-css.es5.js +1 -1
package/dist/bitwrench-util-css.es5.min.js +1 -1
package/dist/bitwrench-util-css.esm.js +1 -1
package/dist/bitwrench-util-css.esm.min.js +1 -1
package/dist/bitwrench-util-css.umd.js +1 -1
package/dist/bitwrench-util-css.umd.min.js +1 -1
package/dist/bitwrench-util-css.umd.min.js.gz +0 -0
package/dist/bitwrench.cjs.js +3 -3
package/dist/bitwrench.cjs.min.js +2 -2
package/dist/bitwrench.cjs.min.js.gz +0 -0
package/dist/bitwrench.css +1 -1
package/dist/bitwrench.es5.js +3 -3
package/dist/bitwrench.es5.min.js +2 -2
package/dist/bitwrench.es5.min.js.gz +0 -0
package/dist/bitwrench.esm.js +3 -3
package/dist/bitwrench.esm.min.js +2 -2
package/dist/bitwrench.esm.min.js.gz +0 -0
package/dist/bitwrench.umd.js +3 -3
package/dist/bitwrench.umd.min.js +2 -2
package/dist/bitwrench.umd.min.js.gz +0 -0
package/dist/builds.json +57 -57
package/dist/bwserve.cjs.js +2 -2
package/dist/bwserve.esm.js +2 -2
package/dist/sri.json +45 -45
package/docs/README.md +76 -0
package/docs/app-patterns.md +264 -0
package/docs/bitwrench-mcp.md +426 -0
package/docs/bitwrench_api.md +2232 -0
package/docs/bw-attach.md +399 -0
package/docs/bwserve.md +841 -0
package/docs/cli.md +307 -0
package/docs/component-cheatsheet.md +144 -0
package/docs/component-library.md +1099 -0
package/docs/framework-translation-table.md +33 -0
package/docs/llm-bitwrench-guide.md +672 -0
package/docs/routing.md +562 -0
package/docs/state-management.md +767 -0
package/docs/taco-format.md +373 -0
package/docs/theming.md +309 -0
package/docs/thinking-in-bitwrench.md +1457 -0
package/docs/tutorial-bwserve.md +297 -0
package/docs/tutorial-embedded.md +314 -0
package/docs/tutorial-website.md +255 -0
package/package.json +11 -3
package/readme.html +5 -4
package/src/mcp/knowledge.js +231 -0
package/src/mcp/live.js +226 -0
package/src/mcp/server.js +216 -0
package/src/mcp/tools.js +369 -0
package/src/mcp/transport.js +55 -0
package/src/version.js +3 -3

package/docs/cli.md ADDED Viewed

@@ -0,0 +1,307 @@
+# CLI
+The `bwcli` command converts files to styled HTML pages. It supports Markdown, HTML, and JSON input, and can produce self-contained offline pages or pages that load bitwrench from a CDN.
+## Installation
+```bash
+npm install -g bitwrench
+```
+Or use `npx` without installing:
+```bash
+npx bwcli README.md
+```
+## Basic usage
+```bash
+# Convert a Markdown file to HTML
+bwcli README.md
+# Specify output file
+bwcli README.md -o index.html
+# Apply a theme
+bwcli README.md -o index.html --theme ocean
+# Create a self-contained offline page
+bwcli README.md -o index.html --standalone
+# Add syntax highlighting
+bwcli README.md -o index.html --highlight
+```
+## Input formats
+The CLI detects the input format by file extension:
+| Extension | Handling |
+|-----------|----------|
+| `.md`, `.markdown` | Parsed with [Quikdown](https://github.com/deftio/quikdown) (bundled zero-dep Markdown parser). Title extracted from first `# heading`. |
+| `.html`, `.htm` | If it is a full HTML document (has `<html>` or `<!DOCTYPE>`), the `<title>` and `<body>` content are extracted. Otherwise, the file is used as-is as body content. |
+| `.json` | If the JSON has a `t` property, it is treated as a TACO object and rendered with `bw.html()`. Otherwise, it is pretty-printed as a code block. |
+## Output
+By default, the output file has the same name as the input with a `.html` extension:
+```bash
+bwcli docs/guide.md       # → docs/guide.html
+bwcli data.json            # → data.html
+```
+Override with `-o`:
+```bash
+bwcli docs/guide.md -o site/index.html
+```
+## Bitwrench injection modes
+By default, the CLI produces plain HTML without bitwrench. Three flags control how bitwrench is included in the output:
+| Flag | Mode | What happens |
+|------|------|-------------|
+| `--standalone` / `-s` | Inline | The entire bitwrench UMD bundle is embedded in a `<script>` tag. Page works offline with no external dependencies. |
+| `--cdn` | CDN | A `<script>` tag loads bitwrench from jsDelivr with an SRI hash for integrity. Requires internet access. |
+| `--no-bw` | None | No bitwrench is included. Plain HTML output. This is the default. |
+When bitwrench is included (`--standalone` or `--cdn`), a small script runs after the page loads to call `bw.loadStyles()`, applying bitwrench's default component styles.
+## Themes
+Apply a built-in theme preset:
+```bash
+bwcli README.md --theme ocean
+bwcli README.md --theme sunset
+bwcli README.md --theme forest
+bwcli README.md --theme slate
+```
+Or specify custom colors as a comma-separated pair of hex values (primary and secondary):
+```bash
+bwcli README.md --theme "#336699,#cc6633"
+```
+Available presets: `teal`, `ocean`, `sunset`, `forest`, `slate`, `rose`, `indigo`, `amber`, `emerald`, `nord`, `coral`, `midnight`.
+Themes require bitwrench to be included (`--standalone` or `--cdn`). If neither is specified, the theme flag is ignored.
+## Additional CSS
+Include an external CSS file:
+```bash
+bwcli README.md -c styles.css -o index.html
+```
+The CSS file's contents are embedded in a `<style>` tag in the output. This works with or without bitwrench injection.
+## Favicon
+Add a favicon to the page:
+```bash
+bwcli README.md -f favicon.ico -o index.html
+bwcli README.md -f https://example.com/icon.png -o index.html
+```
+The value is used directly as the `href` attribute of a `<link rel="icon">` tag.
+## Syntax highlighting
+Include highlight.js for code block syntax highlighting:
+```bash
+bwcli README.md --highlight -o index.html
+```
+This adds the highlight.js CDN stylesheet and script to the output page. Code blocks in the Markdown source get automatic syntax highlighting based on the language specified in the fenced code block.
+## Page title
+The CLI auto-detects the page title from the content:
+- **Markdown**: First `# heading` in the file
+- **HTML**: `<title>` element content
+- **JSON**: The filename
+Override with `--title`:
+```bash
+bwcli README.md --title "My Project Documentation" -o index.html
+```
+## All flags
+```
+bwcli <file> [options]
+Options:
+  -o, --output <file>    Output file path
+  -c, --css <file>       Include external CSS file
+  -t, --theme <name>     Theme preset or hex colors ("primary,secondary")
+  -s, --standalone       Embed bitwrench inline (works offline)
+      --cdn              Link bitwrench via CDN (jsDelivr)
+      --no-bw            Don't inject bitwrench (default)
+      --title <text>     Page title (default: auto-detect)
+  -f, --favicon <path>   Favicon path or URL
+      --highlight        Include highlight.js for syntax highlighting
+  -v, --verbose          Verbose output
+  -h, --help             Print help
+      --version          Print version
+```
+## The `bwcli serve` subcommand — Pipe Server
+`bwcli serve` is a pipe server that turns **any language** into a bwserve backend. It opens two ports:
+- **Web port** (default `:8080`) — browsers connect here via SSE
+- **Input port** (default `:9000`) — your app sends protocol messages here via HTTP POST
+Alternatively, use `--stdin` to pipe newline-delimited JSON from stdin.
+### Usage
+```bash
+# Start the pipe server with default ports
+bwcli serve
+# Custom ports
+bwcli serve --port 8080 --input-port 9000
+# Open browser automatically
+bwcli serve --open
+# Stdin mode: pipe messages from any command
+python sensor.py | bwcli serve --stdin --port 8080
+# Verbose logging (shows all messages)
+bwcli serve -v
+```
+### Sending protocol messages
+Your app sends bwserve protocol messages (JSON) to the input port. All connected browsers update in real time.
+```bash
+# Patch a value:
+curl -X POST http://localhost:9000 \
+  -H "Content-Type: application/json" \
+  -d '{"type":"patch","target":"temp","content":"23.5 C"}'
+# Batch update:
+curl -X POST http://localhost:9000 \
+  -d '{"type":"batch","ops":[
+    {"type":"patch","target":"temp","content":"23.5"},
+    {"type":"patch","target":"humidity","content":"67%"}
+  ]}'
+# r-prefix relaxed JSON is also accepted (for C/embedded):
+curl -X POST http://localhost:9000 -d "r{'type':'patch','target':'temp','content':'23.5'}"
+```
+### Options
+```
+bwcli serve [options]
+Options:
+  -p, --port <number>         Web port for browsers (default: 8080)
+      --input-port <number>   Input port for protocol messages (default: 9000)
+      --stdin                 Read messages from stdin instead of input port
+  -t, --theme <name>          Theme preset or hex colors
+      --open                  Open browser on start
+  -v, --verbose               Verbose output (shows all messages)
+  -h, --help                  Print help
+```
+### How it works
+1. Browser opens `http://localhost:8080` and gets an auto-generated page shell
+2. Shell loads bitwrench, opens SSE connection to `/bw/events/:clientId`
+3. Your app POSTs protocol messages to `http://localhost:9000`
+4. `bwcli serve` broadcasts each message to all connected browsers via SSE
+5. Browser's `bw.apply()` updates the DOM
+Both strict JSON and r-prefix relaxed JSON are accepted on the input port. See [bwserve](bwserve.md) for the full protocol reference.
+## The `bwcli attach` subcommand — Remote Debugging REPL
+`bwcli attach` provides a built-in terminal-based debugger for any bitwrench page. It starts a bwserve instance and waits for a browser to connect via a drop-in `<script>` tag. Once connected, you get an interactive REPL for evaluating JS, inspecting the DOM, taking screenshots, and listening to events.
+### Usage
+```bash
+# Start on default port (7902)
+bwcli attach
+# Custom port
+bwcli attach --port 3000
+# Enable screenshot support
+bwcli attach --allow-screenshot
+# Verbose mode (shows protocol messages)
+bwcli attach -v
+```
+### Connecting a page
+Add this to any HTML page, or paste it into the browser's devtools console:
+```html
+<script src="http://localhost:7902/bw/attach.js"></script>
+```
+The drop-in script automatically loads bitwrench if it's not already on the page, then connects via SSE.
+### REPL commands
+Once connected, you get a `bw>` prompt:
+```
+bw> document.title                    # Evaluate JS expression
+bw> /tree #app 2                      # Show DOM tree
+bw> /screenshot body page.png         # Capture screenshot (requires --allow-screenshot)
+bw> /mount #app card {"title":"Hi"}   # Mount BCCL component
+bw> /render #app {"t":"h1","c":"Hi"}  # Render TACO
+bw> /patch counter 42                 # Update element text
+bw> /listen button click              # Watch DOM events
+bw> /unlisten button click            # Stop watching
+bw> /exec alert('hello')             # Execute JS (fire-and-forget)
+bw> /clients                          # List connected clients
+bw> /help                             # Command reference
+bw> /quit                             # Exit
+```
+### Options
+```
+bwcli attach [options]
+Options:
+  -p, --port <number>        Server port (default: 7902)
+      --allow-screenshot     Enable /screenshot command
+  -v, --verbose              Verbose output
+  -h, --help                 Print help
+```
+For the complete guide, see [bwcli attach documentation](bw-attach.md).
+## Page layout
+The CLI wraps content in a responsive layout:
+- Centered container (max-width 48rem)
+- System font stack (San Francisco, Segoe UI, Roboto, Helvetica, Arial)
+- Comfortable typography (1rem base, 1.6 line-height)
+- Styled code blocks with horizontal scroll
+- Responsive tables with alternating row colors
+- Mobile-friendly (adjusts at 600px breakpoint)
+This layout is designed to produce readable documents without any additional styling. Add `--theme` and `--standalone` (or `--cdn`) for bitwrench-styled components on top of this base.

package/docs/component-cheatsheet.md ADDED Viewed

@@ -0,0 +1,144 @@
+# Component Cheat Sheet
+> **Before you write custom TACO for a common UI pattern, check this list.**
+> Bitwrench ships 50+ ready-made `make*()` factories. Each returns a Level 0 TACO object.
+## Full Component Table
+| Component | Key Props | Capabilities | Handles / Slots |
+|-----------|-----------|-------------|----------------|
+| **Tables & Data** | | | |
+| makeTable | data, columns, sortable, pageSize, onRowClick | Click-to-sort (on by default), pagination, row selection, custom column renderers | -- |
+| makeTableFromArray | data (2D array), headerRow, sortable | Convert CSV/spreadsheet data to sortable table | -- |
+| makeDataTable | title, data, columns, responsive | Title heading + responsive scroll wrapper around makeTable | -- |
+| makeBarChart | data, labelKey, valueKey, title, color, formatValue | Pure-CSS vertical bar chart, no external library | -- |
+| **Interactive** | | | |
+| makeCarousel | items, autoPlay, interval, showControls | Auto-play, pause-on-hover, keyboard nav, dot indicators | goToSlide(i), next(), prev(), play(), pause(), getActiveIndex() |
+| makeTabs | tabs [{label,content}], activeIndex | Arrow/Home/End keys, full WAI-ARIA, click switching | setActiveTab(i), getActiveTab() |
+| makeAccordion | items [{title,content}], multiOpen | Smooth animations, ARIA, multi-open option | toggle(i), openAll(), closeAll() |
+| makeModal | title, content, footer, size, onClose | ESC dismiss, backdrop click close, size variants | open(), close() |
+| makeToast | title, content, variant, delay, position | Auto-dismiss (5s default), 6 position options | dismiss() |
+| makeDropdown | trigger, items, align, variant | Outside-click-to-close, divider support | -- |
+| makePopover | trigger, title, content, placement | Click-outside-to-close, 4 placements | -- |
+| makeTooltip | content, text, placement | Show on hover/focus, role=tooltip, 4 placements | -- |
+| **Content** | | | |
+| makeCard | title, content, footer, image, variant, shadow | All props accept TACO (not just strings), image positions, shadow variants, hoverable | slots: setTitle/getTitle, setContent/getContent, setFooter/getFooter |
+| makeStatCard | value, label, change, variant, prefix, suffix | Dashboard KPI with change indicator (green/red arrows) | slots: setValue/getValue, setLabel/getLabel |
+| makeAlert | title, content, variant, dismissible | Dismissible close button, 8 color variants | -- |
+| makeBadge | text, variant, pill, size | Pill shape option, sm/lg sizes | -- |
+| makeProgress | value, max, variant, striped, animated | Striped + animated variants, ARIA | setValue(n), getValue() |
+| makeHero | title, subtitle, actions, variant, size, backgroundImage | Background image with overlay, centered/left layouts | -- |
+| makeSection | title, subtitle, content, variant, spacing | Semantic section wrapper with spacing control | -- |
+| makeFeatureGrid | features [{icon,title,desc}], columns, centered | Responsive icon+title+desc grid | -- |
+| makeCTA | title, description, actions, variant | Call-to-action block with action buttons | -- |
+| makeCodeDemo | title, description, code, result | Code + live output in tabbed view, copy button | -- |
+| makeMediaObject | src, alt, title, content, reverse, imageSize | Image + text side-by-side, reversible | -- |
+| makeTimeline | items [{title,content,date,variant}] | Vertical timeline with colored markers | -- |
+| makeStepper | steps [{label,desc}], currentStep | Step progress indicator with completed/active/pending states | -- |
+| makeListGroup | items, flush, interactive | Interactive click items, flush variant for cards | -- |
+| makeAvatar | src, alt, initials, size, variant | Initials fallback when no image, 4 sizes | -- |
+| makeSkeleton | variant, width, height, count | Pulse animation placeholder (text/circle/rect) | -- |
+| makeSpinner | variant, size, type | Border/grow animation types, 3 sizes | -- |
+| **Navigation** | | | |
+| makeNav | items [{text,href,active}], pills, vertical | Pill/vertical variants, disabled items | -- |
+| makeNavbar | brand, brandHref, items, dark | Dark variant, brand link | -- |
+| makeBreadcrumb | items [{text,href}] | aria-label, aria-current on active item | -- |
+| makePagination | pages, currentPage, onPageChange, size | Page change callbacks, sm/lg sizes | -- |
+| **Forms** | | | |
+| makeForm | children, onsubmit | Form wrapper with default preventDefault | -- |
+| makeFormGroup | label, input, help, validation, feedback, required | Required indicator (*), validation feedback (valid/invalid) | -- |
+| makeInput | type, placeholder, value, disabled, oninput | All HTML5 types, bw_form_control styling | -- |
+| makeTextarea | placeholder, value, rows, disabled | Multi-line input, bw_form_control styling | -- |
+| makeSelect | options [{value,text}], value, disabled | Dropdown select, bw_form_control styling | -- |
+| makeCheckbox | label, checked, id, name, disabled | Label-for-id linking, bw_form_check styling | -- |
+| makeRadio | label, name, value, checked, id | Label-for-id linking, radio group support | -- |
+| makeSwitch | label, checked, id, name, disabled | Toggle switch with label linking | -- |
+| makeSearchInput | placeholder, onSearch, onInput | Enter to search, clear button appears on input | -- |
+| makeChipInput | chips, placeholder, onAdd, onRemove | Enter to add, click X to remove, backspace last | addChip(v), removeChip(v), getChips(), clear() |
+| makeFileUpload | accept, multiple, onFiles, text | Drag-and-drop zone, styled file input | -- |
+| makeRange | min, max, step, value, label, showValue | Live value display next to slider | -- |
+| **Buttons** | | | |
+| makeButton | text, variant, size, disabled, onclick, type | 8 variants + outline-* variants, sm/lg sizes | -- |
+| makeButtonGroup | children, size, vertical | Shared border-radius, vertical/horizontal layout | -- |
+| **Layout** | | | |
+| makeContainer | fluid, children | Centered max-width or full-width fluid | -- |
+| makeRow | children, gap | Flexbox row with gap (1-5) | -- |
+| makeCol | size, offset, content | Responsive: size as number or {xs,sm,md,lg,xl} | -- |
+| makeStack | children, direction, gap | Vertical/horizontal flex stack | -- |
+## How to Use Handles
+Components with handles expose imperative methods via `el.bw`. Use `bw.mount()` instead of `bw.DOM()` to get the element reference:
+```javascript
+// Mount and get element reference
+var el = bw.mount('#target', bw.makeCarousel({ items: slides, autoPlay: true }));
+// Call handle methods directly
+el.bw.goToSlide(2);
+el.bw.pause();
+var idx = el.bw.getActiveIndex();  // => 2
+// Works with any component that has handles
+var modal = bw.mount('#modal', bw.makeModal({ title: 'Confirm', content: 'Sure?' }));
+modal.bw.open();   // show the modal
+modal.bw.close();  // hide it
+```
+When you don't have the element reference, use `bw.message()`:
+```javascript
+bw.message('#my-carousel', 'goToSlide', 2);
+bw.message('.bw_uuid_abc123', 'next');
+```
+See [State Management -- Level 1.5](state-management.md#level-15-component-handles) for the full handle/slots guide.
+## How to Use Slots
+Slot-based components auto-generate `el.bw.setName()` / `el.bw.getName()` pairs for content areas:
+```javascript
+var card = bw.mount('#info', bw.makeCard({ title: 'Stats', content: '0' }));
+card.bw.setTitle('Revenue');                  // update just the title
+card.bw.setContent({ t: 'b', c: '$42k' });   // accepts TACO objects
+card.bw.getTitle();                           // => 'Revenue'
+```
+Slot setters update only the targeted child -- input focus, scroll, and animation state in siblings are preserved.
+Build your own with `o.slots`:
+```javascript
+{
+  t: 'div', c: [
+    { t: 'h3', a: { class: 'title' }, c: 'Default' },
+    { t: 'div', a: { class: 'body' }, c: 'Content' }
+  ],
+  o: {
+    slots: { title: '.title', body: '.body' }
+    // => el.bw.setTitle(), el.bw.getTitle(), el.bw.setBody(), el.bw.getBody()
+  }
+}
+```
+## Factory Dispatcher
+Use `bw.make(type, props)` for data-driven component creation:
+```javascript
+bw.make('card', { title: 'Hello' });  // same as bw.makeCard({ title: 'Hello' })
+// Data-driven layout
+var layout = [
+  { type: 'card', props: { title: 'Stats' } },
+  { type: 'alert', props: { content: 'Warning!', variant: 'warning' } }
+];
+bw.DOM('#app', { t: 'div', c: layout.map(function(item) {
+  return bw.make(item.type, item.props);
+})});
+```
+---
+*See [Component Library](component-library.md) for full signatures and examples. See [LLM Guide](llm-bitwrench-guide.md) for the compact API reference.*