You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The scaffold teaching-coverage gate added in the coverage-gate PR classifies every @webjsdev/core export as demoed (a runnable gallery example), internal-exempt (framework plumbing), or deferred (agent-facing, but no runnable gallery demo yet). 29 exports are currently deferred. They are real APIs an agent may reach for, so the gallery should teach each with a real, commented demo. Converting a deferred exemption into a { demo } pointer is the intended way to shrink the list (and is the follow-through that makes the gate drive demos, not exemptions).
Prioritise the highest-frequency agent APIs first, then chip away:
Suspense (page-level streaming) and css / shadow-DOM static styles are headline surfaces that deserve their own feature demos.
navigate / redirect are currently prose-only in the routing/boundaries demos; give them a runnable button/handler (navigate) and a route (redirect).
The lit-parity directives (unsafeHTML, ref/createRef, guard, templateContent, asyncAppend/asyncReplace, until, live, keyed) can extend the existing app/features/directives demo, which today only shows repeat + watch.
The signals extras (computed, effect, batch) and the context API (createContext + Context*) fit a components/signals demo.
Each conversion: add the runnable usage to a gallery file (new or existing), then flip that export's entry in gallery-coverage.json from { exempt: "deferred: ..." } to { demo: "<gallery file>" }. The gate verifies the pointed file actually references the symbol.
Implementation notes (for the implementing agent)
Manifest + gate: test/scaffolds/gallery-coverage.json (source of truth) and test/scaffolds/gallery-coverage.test.js (the reconcile() gate; the every @webjsdev/core export is demoed or exempted test prints the live deferred list).
Gallery demos live under packages/cli/templates/gallery/app/features/<name>/ with logic in .../modules/<name>/; the home index features array is in packages/cli/lib/create.js (two copies: full-stack + saas home), and test/scaffolds/scaffold-gallery.test.jsFEATURES asserts each.
Follow the webjs-scaffold-sync skill for every surface; each new feature page carries a webjs-scaffold-placeholder marker and dense teaching comments.
Landmine: the gate's demo check is a word-boundary match on the symbol, so a demo that only mentions the API in prose still fails unless it truly imports/uses it (that is the point). Respect the prose-punctuation invariant (release: bump core/server/cli versions, honest engines fields #11) in comments.
Verify by generating + booting a full-stack app and hitting each new route (webjs check should show only no-scaffold-placeholder).
Acceptance criteria
Each converted export has a runnable gallery demo and a { demo } entry in gallery-coverage.json
The gate's deferred count drops accordingly; the coverage test stays green
scaffold-gallery.test.js asserts any new feature route
A freshly generated full-stack app boots and serves each new demo route
Docs/scaffold rule-file feature lists updated for any new feature folder
Problem
The scaffold teaching-coverage gate added in the coverage-gate PR classifies every
@webjsdev/coreexport as demoed (a runnable gallery example), internal-exempt (framework plumbing), or deferred (agent-facing, but no runnable gallery demo yet). 29 exports are currentlydeferred. They are real APIs an agent may reach for, so the gallery should teach each with a real, commented demo. Converting adeferredexemption into a{ demo }pointer is the intended way to shrink the list (and is the follow-through that makes the gate drive demos, not exemptions).Deferred set (see
test/scaffolds/gallery-coverage.json, reasons carry the doc pointer):Suspense, css (shadow styles), Task, TaskStatus, computed, effect, batch, createContext, ContextProvider, ContextConsumer, ContextRequestEvent, unsafeHTML, ref, createRef, guard, templateContent, asyncAppend, asyncReplace, until, live, keyed, navigate, redirect, revalidate, richFetch, disableClientRouter, enableClientRouter, cache (lit directive), cspNonce.
Design / approach
Prioritise the highest-frequency agent APIs first, then chip away:
static stylesare headline surfaces that deserve their own feature demos.app/features/directivesdemo, which today only showsrepeat+watch.Each conversion: add the runnable usage to a gallery file (new or existing), then flip that export's entry in
gallery-coverage.jsonfrom{ exempt: "deferred: ..." }to{ demo: "<gallery file>" }. The gate verifies the pointed file actually references the symbol.Implementation notes (for the implementing agent)
test/scaffolds/gallery-coverage.json(source of truth) andtest/scaffolds/gallery-coverage.test.js(thereconcile()gate; theevery @webjsdev/core export is demoed or exemptedtest prints the live deferred list).packages/cli/templates/gallery/app/features/<name>/with logic in.../modules/<name>/; the home index features array is inpackages/cli/lib/create.js(two copies: full-stack + saas home), andtest/scaffolds/scaffold-gallery.test.jsFEATURESasserts each.webjs-scaffold-syncskill for every surface; each new feature page carries awebjs-scaffold-placeholdermarker and dense teaching comments.webjs checkshould show onlyno-scaffold-placeholder).Acceptance criteria
{ demo }entry ingallery-coverage.jsonscaffold-gallery.test.jsasserts any new feature route