@bluestep-systems/bspecs 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluestep-systems/bspecs",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Spec-driven BlueStep development with AI agents — scaffolder and project conventions for Claude Code",
   "type": "module",
   "bin": {

package/templates/claude/instructions/index.md.template

@@ -11,6 +11,7 @@ Entries read: `path — what it covers. Load when <trigger>.` Match the trigger
 ## reference/ — single-topic platform and API detail
 
 - [reference/api-patterns.md](reference/api-patterns.md) — B API usage: Java optionals (`.opt()/.orElse()`), field types and access, `mergeTag()` L/F/I/H codes, multi-entry-form (MEF) entries, query access, Java collections, writing date/datetime fields, `B.commit()` and formula triggers, endpoint request/response, base64, user/session. Load when calling the `B` API, reading or writing fields, or wiring an endpoint's request/response.
+- [reference/b-include-element.md](reference/b-include-element.md) — `<b-include>` browser custom element that fetches HTML from a URL and renders it inline (client-side `<jsp:include>`/SSI); `src`/`run-scripts`/`csrf` attrs, spinner/error behavior, trusted-template-only (neutralized in user HTML). Load when injecting a dynamic async HTML fragment in the browser.
 - [reference/blueiq-credit-integration-playbook.md](reference/blueiq-credit-integration-playbook.md) — step-by-step playbook for wiring a new OpenAI/AI feature into the BlueIQ credit gate and ledger. Load when adding an AI feature that must consume BlueIQ credits.
 - [reference/chronounit-months.md](reference/chronounit-months.md) — `ChronoUnit.MONTHS.between` counts elapsed (day-aware) months, not calendar-month boundaries. Load when computing a month difference or porting SQL `DATEDIFF(MONTH)`.
 - [reference/code-patterns.md](reference/code-patterns.md) — working BsJs skeletons: queries, MergeReport server/client bridge, endpoints, error handling, performance (per-row queue, lazy init), component import, debugging. Load when starting a query, MergeReport, or endpoint and you want a known-good pattern.
@@ -31,6 +32,7 @@ Entries read: `path — what it covers. Load when <trigger>.` Match the trigger
 - [reference/id-full-vs-short.md](reference/id-full-vs-short.md) — `Id.toString()` is the full `ClassID___ShortID`; `shortId()` is just the trailing number; `optById` needs the full form. Load when round-tripping an entry id or calling `optById`.
 - [reference/internal-loopback-fetch.md](reference/internal-loopback-fetch.md) — endpoint-to-endpoint loopback within an org uses `B.net.fetch` on a relative path with `credentials:true`, not the external `httpRequester`. Load when one endpoint calls another in the same org.
 - [reference/localdate-parse.md](reference/localdate-parse.md) — `Java.Time.LocalDate` is a TypeScript namespace only; use `B.time.LocalDate` for runtime `parse()`/`now()`. Load when parsing or creating a LocalDate.
+- [reference/merge-report-async-loading.md](reference/merge-report-async-loading.md) — the "Asynchronous Loading" option on a Data Merge Report lazy-loads it AFTER the page resolves (BSJS used an `async` metadata property, not the checkbox); parent→child fan-out, the obsolete `formFooter` hack, and the script-timing gotcha. Load when a merge report is slow or should lazy-load, or page script depends on async merge content.
 - [reference/merge-report-memo-json.md](reference/merge-report-memo-json.md) — the "MergeReport + memo field JSON" framework: embed a custom interactive widget on a form that persists its state as JSON in a hidden memo field. Load when building a stateful custom widget on a form.
 - [reference/merge-report-static-index.md](reference/merge-report-static-index.md) — with a `static/` bundle, `static/index.html` is the page and `app.ts` `B.out` is NOT injected; put the mount + config island in `index.html` and run the client on `DOMContentLoaded`. Load when a MergeReport has a `static/` bundle.
 - [reference/merge-report-urls.md](reference/merge-report-urls.md) — BSJS equivalents of relatescript `lookupMergeReport`/`lookupMergeReportScript`, and how to get `viewUrl`/`printUrl`. Load when looking up a MergeReport URL in code.

package/templates/claude/instructions/reference/b-include-element.md.template

@@ -0,0 +1,46 @@
+---
+description: "`<b-include>` is a browser custom element that fetches HTML from a URL and renders it inline — client-side `<jsp:include>`/SSI for dynamic async content; trusted-template only (neutralized in user-supplied HTML)"
+---
+
+`<b-include>` is a **browser custom element** (defined in `dom.ts:432-560`) that
+**fetches HTML from a URL and renders it inline** — think client-side `<jsp:include>`
+/ server-side-include for the browser. Use it for dynamic, async page fragments.
+
+**Syntax** — must use an explicit closing tag (it is **not** self-closing):
+```html
+<b-include src="/path/to/fragment.jsp"></b-include>
+```
+
+**Attributes**
+
+| Attribute     | Values                | Purpose |
+| ------------- | --------------------- | ------- |
+| `src`         | URL                   | Content to fetch. **Reactive** — changing it re-fetches automatically. |
+| `run-scripts` | `"true"` \| (omit)    | When `"true"`, `<script>` tags in the fetched HTML are re-inserted so the browser executes them. Default: scripts are inert. |
+| `csrf`        | `"true"` \| `"false"` \| (omit) | Force CSRF handling. Omit for auto-detect: same-origin → `csrf.fetch`, cross-origin → plain fetch. |
+
+**Examples**
+```html
+<!-- Basic same-origin include (CSRF token auto-attached) -->
+<b-include src="/shared/content/fragment.jsp"></b-include>
+
+<!-- Include a fragment and run its <script> tags -->
+<b-include src="/path/with/scripts.html" run-scripts="true"></b-include>
+
+<!-- Cross-origin with forced CSRF off (remote must send CORS headers) -->
+<b-include src="https://other.example.com/widget" csrf="false"></b-include>
+```
+
+**Behavior**
+- Shows a spinner while loading; shows an error box with a **"Reload"** link on failure.
+- Re-setting `src` aborts the in-flight request and re-fetches.
+- Removal from the DOM aborts any pending request.
+- Drivable from JS via properties: `el.src`, `el.runScripts`, `el.csrf`.
+
+**Security — trusted templates only.** `<b-include>` is **neutralized in user-supplied
+content** by `HTMLFilter.java:46` (rewritten to `<xxb-includexx>`) to prevent injection.
+Only use it in **trusted templates**, never in user-editable HTML. The Zesty editor
+whitelists it as `b-include[src|run-scripts|csrf]` (`zesty3.ts:130`).
+
+For the server-side config alternative (a merge report that lazy-loads after the page),
+see [merge-report-async-loading](merge-report-async-loading.md).

package/templates/claude/instructions/reference/merge-report-async-loading.md.template

@@ -0,0 +1,41 @@
+---
+description: A Data Merge Report's "Asynchronous Loading" option makes it lazy-load AFTER the rest of the page resolves instead of as part of the initial request; in BSJS this was an `async` metadata property rather than the checkbox
+---
+
+A BlueStep **Data Merge Report** has an **"Asynchronous Loading"** checkbox under
+*Advanced Usage Options* (Step 3 of the merge-report edit wizard). Turning it on
+makes the merge report **resolve in a lazy-load rather than as part of the initial
+page request** — the rest of the page renders first, then the merge report loads
+in separately so a heavy merge doesn't slow everything else down.
+
+This is **not a new feature**. It maps directly to the underlying DB object and has
+existed for a long time. **BSJS had no toggle** — you set an `async` property in the
+component metadata, which inserted a layer of indirection over that same DB object.
+Removing that BSJS layer is what surfaced the plain checkbox; it only *looks* new to
+anyone who previously only used BSJS.
+
+**Parent → child behavior.** When a merge report calls another async merge report,
+the **parent's HTML resolves first**, the page loads, and then each async child
+loads separately — so a parent merge report that fans out to N children can give
+each child its own independent loader. (The resident-med report does exactly this:
+a nasty merge that renders per resident, switched to async, **loads in batches of
+3 at a time**.)
+
+**Good use cases:** heavy/slow merges; merge reports embedded on a form; a parent
+merge report aggregating several child merge reports; query-driven layouts where
+displayed merge-report fields can stream in after the header data.
+
+**Gotcha — script timing.** Because the content is no longer present at initial page
+load, any page script that **expects the async merge report's DOM/data to already be
+there will break**. If you have client code depending on the merge report, gate it on
+the async content actually arriving rather than on initial `DOMContentLoaded`.
+
+**Obsolete hack.** Older setups added a marker like
+`htmlCode += '<span id="formFooter"></span>'` to force the async merge report to load
+properly. With the current setup this should **no longer be necessary** — don't carry
+it forward into new code.
+
+For dynamic async content driven from the client (rather than this server-side
+config), see [b-include element](b-include-element.md). Related merge-report detail:
+[merge-report-static-index](merge-report-static-index.md),
+[merge-report-memo-json](merge-report-memo-json.md).