Fully working plain-browser app on the latest 2.5.x line — consolidate lab findings & blockers (#118, #119, #107)

[jeanmachuca]

Summary

Goal: a plain front-end QCObjects app — the kind demonstrated across the QCObjects-Labs labs — should run unmodified on the latest release line (2.5.x). Today it only works on the 2.4 line (qcobjects@2.4.99 + qcobjects-sdk@2.4.66); the latest version fails at load time, at type-check time, and at scaffold time. This issue consolidates the lab findings (with working references) and drives the remaining blockers to closure so the latest version is actually usable.

Lab references (verified ground truth)

These were built and verified end-to-end (headless Chromium + framework debug logger) during the QCObjects discovery labs:

• Working 2.4-line demo app — https://github.com/QCObjects-Labs/qcobjects-web
  A from-scratch app with a modern class-based component using the external
  .tpl.html template mechanism (smart widget → generic <quick-component> →
  XHR fetch of templates/components/*.tpl.html → native shadow root).
• Hello-world with vendored browser bundles — https://github.com/QCObjects-Labs/hello-qcobjects
  Demonstrates that even the 2.4 browser bundles lazily require Node core
  built-ins (node:process, node:fs, node:path, node:url) and need a
  benign window.require stub to load — which the latest line must eliminate.
• Lab findings & tooling write-up — https://github.com/QCObjects-Labs/labs-docs
  FINDINGS.md documents the load mechanism, componentClass resolution,
  nested components, and debugging; APPENDIX-TOOLING.md documents the
  verification setup.
• Agent skill — https://github.com/qcobjects-skills/scaffolding
  The distilled, installable recipe (npx skills add qcobjects-skills/scaffolding).

Current blockers on latest (2.5.x)

• Shipped browser builds embed Node core built-ins (node:fs, node:process), so neither <script> nor <script type="module"> loads in a browser #118 — Shipped browser builds embed Node core built-ins; none of the
  shipped builds (public/browser/QCObjects.js, build/QCObjects.js,
  public/esm/index.mjs) load in a plain browser, so the app does nothing.
• qcobjects npm package ships broken TypeScript type declarations (TS2305 on every named export) #119 — qcobjects npm package ships broken TypeScript declarations
  (TS2305 on every named export), so a TS app cannot type-check against it.
• latest dist-tag is a pre-release (-beta) #107 — latest npm dist-tag points at a -beta pre-release, so
  npm install qcobjects does not even install a stable latest.

Acceptance criteria for "fully working app on the latest version"

1. npm install qcobjects@latest (stable tag) + a plain esbuild/Vite ESM app:
   import * as QCObjects from "qcobjects" initializes with no shims —
   no window.require, no Node built-in stubs.
2. A classic <script> pointing at a shipped browser build defines the global
   API (CONFIG, Class, New, Component, Package, …) as documented.
3. npx tsc --noEmit on a TS app importing qcobjects passes (no TS2305).
4. The external .tpl.html mechanism behaves identically to the 2.4-line
   reference (qcobjects-web): widget → generic component → XHR → shadow-root
   render, verified via window.logger.debugEnabled = true.
5. No Node core module (node:fs, node:process, node:path, node:url) is
   required or loaded in any browser execution path.
6. The lab's 2.4-line apps upgrade to latest with zero code changes other
   than the dependency version bump.

Suggested work items

• Ship a browser build that loads via plain <script> and via <script type="module"> without Node built-ins (Shipped browser builds embed Node core built-ins (node:fs, node:process), so neither <script> nor <script type="module"> loads in a browser #118).
• Publish correct index.d.ts declarations for every public export (qcobjects npm package ships broken TypeScript type declarations (TS2305 on every named export) #119).
• Move the latest dist-tag to a stable (non--beta) release (latest dist-tag is a pre-release (-beta) #107).
• Type-check declaration tests (tsc --noEmit) in CI.
• Browser smoke test (headless) that loads the framework and renders an external-.tpl.html component.
• Optionally adopt the lab apps (qcobjects-web, hello-qcobjects) as CI fixtures so regressions are caught against real-world usage.

Related

• Shipped browser builds embed Node core built-ins (node:fs, node:process), so neither <script> nor <script type="module"> loads in a browser #118, qcobjects npm package ships broken TypeScript type declarations (TS2305 on every named export) #119, latest dist-tag is a pre-release (-beta) #107
• QCObjects-Labs organization: https://github.com/QCObjects-Labs