solid-showcase
Use when building or modifying a JSON-driven walkthrough site with @jeswr/solid-showcase — authoring or validating walkthrough documents, rendering the four showcase pages, the walkthrough UI components (stepper, try-live, launcher, ecosystem map, persona card), the walkthrough.v1.json schema artifact, or the deploy helpers under ./next (zone rewrites, env matrix, vercel.json, health routes, metadata).
- License 许可
- MIT
- 所属仓库
- jeswr/solid-sdk
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- solid-showcase
- description
- Use when building or modifying a JSON-driven walkthrough site with @jeswr/solid-showcase — authoring or validating walkthrough documents, rendering the four showcase pages, the walkthrough UI components (stepper, try-live, launcher, ecosystem map, persona card), the walkthrough.v1.json schema artifact, or the deploy helpers under ./next (zone rewrites, env matrix, vercel.json, health routes, metadata).
02 资源文件 31
- 许可证LICENSE1.0 KB
- 参考文档package.json1.7 KB
- 参考文档README.md4.0 KB
- 参考文档schema/walkthrough.v1.json13.2 KB
- 脚本scripts/generate-schema.mjs692 B
- 其他src/components/chapter-player.tsx4.0 KB
- 其他src/components/demo-identity-card.tsx2.3 KB
- 其他src/components/ecosystem-map.tsx6.0 KB
- 其他src/components/launcher.tsx3.3 KB
- 其他src/components/status-dot.tsx782 B
- 其他src/components/try-live.tsx2.3 KB
- 脚本src/components/use-service-status.ts3.8 KB
- 脚本src/document.ts3.3 KB
- 脚本src/index.ts2.8 KB
- 脚本src/next/index.ts6.3 KB
- 其他src/pages/showcase-chapter-page.tsx4.0 KB
- 其他src/pages/showcase-compliance-page.tsx3.4 KB
- 其他src/pages/showcase-landing.tsx6.3 KB
- 其他src/pages/showcase-layout.tsx2.0 KB
- 脚本src/schema.ts9.6 KB
- 脚本src/validate.ts13.2 KB
- 其他test/components.test.tsx9.1 KB
- 脚本test/domain-generic.test.ts2.3 KB
- 脚本test/next-helpers.test.ts4.8 KB
- 其他test/pages.test.tsx5.1 KB
- 脚本test/parse-walkthrough.test.ts8.7 KB
- 脚本test/schema-sync.test.ts2.7 KB
- 脚本test/support/example-document.ts10.7 KB
- 参考文档tsconfig.build.json306 B
- 参考文档tsconfig.json615 B
- 脚本vitest.config.ts396 B
03 SKILL.md 正文
<!-- AUTHORED-BY Claude Fable 5 -->
Work with @jeswr/solid-showcase
One validated walkthrough document drives the whole site. Author the document, validate it
with parseWalkthrough, render it with the four page components, and wire deploys with the
./next helpers. Never fork document content into components — the single registry is the
point.
The invariants parseWalkthrough enforces
All are hard errors, all reported AT ONCE, each with a stable code and a message naming
the chapter/step/role/check:
| code | rule |
|---|---|
registry-key-mismatch |
every registry.apps record key equals its entry's slug |
unknown-try-live-app / unknown-role-app / unknown-launcher-app |
every reference resolves in registry.apps |
duplicate-launcher-app |
launcherOrder has no duplicates |
duplicate-role-slug / center-role |
role slugs unique; exactly one center: true role matching registry.center |
unknown-role-scene |
roles[].scene names an existing chapter scene |
chapter-scene-order / duplicate-chapter-slug |
scenes contiguous 1..N in array order; slugs unique |
lead-budget / step-budget / min-steps |
editorial word/step budgets (defaults 40/65/2) |
underneath-required / underneath-length |
underneathRequired ⇒ non-empty points, each ≥ minUnderneathChars (default 20) |
unknown-compliance-chapter / compliance-scene-mismatch |
checks resolve to chapters with matching scenes |
editorial-floor |
overrides only TIGHTEN the schema floors (minSteps ≥ 2, minUnderneathChars ≥ 20) |
persona-honesty |
persona.descriptor must contain "fictional" or "simulated" |
editorialFindings(doc) returns the budget findings without throwing (CI gate:
expect(editorialFindings(doc)).toEqual([])). walkthroughWarnings(doc) carries the
non-fatal role-first naming advisory (modelledOn must not appear inside appName).
Schema rules
- Schema-first: plain
z.objects, types inferred.brandingandthemeare COMPOSED from@jeswr/solid-showcase-kit(brandingConfigSchema,themeSpecSchema) — never redeclare them here; kit owns those contracts, and kit never imports from showcase (acyclic edge). - The artifact
schema/walkthrough.v1.jsonis GENERATED: after any schema change runpnpm run build && pnpm run generate:schemaand commit the artifact —test/schema-sync.test.tsfails on drift. registry.apps[].podRoutes(optional, additive) declares an app's authenticated pod API routes; it exists soenvMatrixcan require the forwarded-headers trust var on exactly those projects.
Rendering rules
ShowcaseLayoutis client-side ("use client"): it builds the disclaimer pack viadocumentDisclaimerPack(doc)(cookie prefix defaults to{deploy.slug}-demo-consent-), resolves the shell theme from the registry entry at path "/" (neutral fallback otherwise), and renders kit AppShell variant "own" + Launcher + ConsentInterstitial.- Landing/chapter/compliance renderers are server-safe; they pass only serializable document data into the client building blocks.
- Chapter routes live at
/chapters/{slug}, the lens at/compliance. Guard unknown slugs withchapterBySlug(doc, slug)before renderingShowcaseChapterPage— it throws on unknown slugs.ShowcaseCompliancePagethrows whendoc.complianceis absent; only route to it when configured. - Honest degradation is a contract, not a style: try-live and launcher entries for
undeployed zones stay VISIBLE as href-less placeholder links with
aria-disabledand an explanation. Never hide them, never leave a navigable href to a dead zone.
Deploy helpers (./next)
zoneRewrites(doc, { env?, fallbackSuffix? })— two rules per zone app (prefix,prefix/:path+); unset env vars fall back tohttps://{slug}.invalidso they can never route anywhere real. Zone URLs are read at BUILD time — changing one needs a shell redeploy, and the build env allowlist must include the zone vars.envMatrix(doc)— zone-URL vars target the shell project; the{envPrefix}_TRUST_FORWARDED_HEADERS=1spec targets exactly thepodRoutesapps.appVercelJson(app, doc)— pair with a project-levelrootDirectoryofapps/{slug}and CLEARED project-level build overrides (they silently win oververcel.json).healthRoute(service)→export const { GET } = healthRoute("{slug}"); the payload is honestlysimulated: true.showcaseMetadata(doc)is always noindex/nofollow.
Domain-generic gate (the whole point)
This package is a GENERIC multistakeholder walkthrough framework. No use-case or domain
string may enter src/, tests, docs, or shipped artifacts — test/domain-generic.test.ts
greps the whole package for a banned-term roster and must stay empty. Real walkthrough
documents (and their golden tests) live in consumer repositories; the fixture here is a
fictional trail-expedition flow. Never "improve" the fixture with real-world content.
Verify API usage against the published dist, run the workspace gate after changes, and never weaken the malformed-document suite or the grep gate.
04 同仓库更多 Skills
storage-conformance
Work on @jeswr/storage-conformance, the shared storage conformance suite package in the Solid SDK workspace.
fetch-rdf-engine-tests
Maintain fetch-rdf's real Node WASM parser integration tests without introducing a reverse engine dependency in fetch-rdf.
alpha
Use when checking fixtures, including folded YAML descriptions.
widget
Use when testing package skills: YAML quoting works.
web-seo
Use when improving technical and entity SEO for a modern personal, portfolio, documentation, or marketing site, including crawlable HTML, canonical metadata, sitemap and robots, Person/ProfilePage JSON-LD, Core Web Vitals, and honest ranking expectations.
solid-wac
Use when implementing or auditing Solid server WAC authorization, ACL creation and inheritance, auxiliary-resource escalation, method-to-mode mapping, 401 versus 403 challenges, WAC-Allow, or defensive typed ACL parsing with @solid/object and @rdfjs/wrapper.