Field report: bwserve discoverability gaps and API feedback#79
Open
deftio wants to merge 3 commits into
Open
Conversation
… feedback Field report from building a ~5,500 LOC production app on bitwrench/bwserve. Covers what works well, the documentation/discoverability gap (the main issue), 4 genuine API gaps (sendAction naming, multi-field forms, modal primitive, register string bodies), JS-first styling insights, and LLM-driven development feedback. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…roken html2canvas is vendored and served. The issue was the allowScreenshot: true server option defaulting to false. Another discoverability problem, not a missing feature. Updated LLM development loop section accordingly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
After reviewing "Thinking in Bitwrench" guide in detail: Sections 1-6, 8-10 cover mental model, JS-first styling, bw.s(), function-valued attrs, component levels, and composition patterns well. The gap is Section 7 (bwserve) which shows 8 of ~13 BwServeClient methods and misses mount, message, inspect, screenshot, sendAction. Revised executive summary and discoverability section to give credit where due and focus feedback on bwserve docs specifically. Also noted bitwrench runs in three modes (pure client, shim/loader, bwserve) and this report covers bwserve mode only. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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.
Summary
Field report from building Boilerroom (~5,500 LOC, 5 tabs, 31 AI panelists, 3 backends, 12 DB tables) on bitwrench/bwserve over ~3 days.
Key finding: Bitwrench is more capable than it appears. The main issue is discoverability — a competent developer built a full app without finding
client.mount(), wrote 3,019 lines of CSS instead of using JS-first styling with function-valued TACO attributes, hand-coded Enter key handlers that bwclient.js already provides, and never foundbw.loadStyles().What this report covers
data-bw-action, component model, BCCL — no changes needed)bw._bwClient.sendAction()should bebw.sendAction()— the underscore prefix discourages using the primary client→server pathdata-bw-actiononly resolves oneinputValueclient.register()string bodies — no syntax highlighting or linting for utility functionsa.styleas JS strings + function-valued attributes (hydration-time and creation-time via IIFE) already solve style composition. This should be documented as the primary styling approach.client.inspect()works,client.screenshot()needs html2canvas bundledRecommended action
One opinionated guide ("How to build a bwserve app") that leads with the right patterns would prevent most of the friction documented here. The framework is ready; the on-ramp needs work.
File
dev/boilerroom-field-report.md— Full report with code examples and recommendations🤖 Generated with Claude Code