Skip to content

docs: @vertz/schema package design plan#6

Merged
viniciusdacal merged 3 commits intomainfrom
docs/schema-design
Feb 4, 2026
Merged

docs: @vertz/schema package design plan#6
viniciusdacal merged 3 commits intomainfrom
docs/schema-design

Conversation

@viniciusdacal
Copy link
Copy Markdown
Contributor

Summary

  • Adds the complete design plan for @vertz/schema — a TypeScript-first schema validation library following the Zod v4 API surface
  • Covers public API surface, architecture (dual type params, error system, parse context), package structure, 7 implementation phases, testing strategy, and gap analysis
  • Zero runtime dependencies, OpenAPI v3.1 / JSON Schema output as first-class citizen, named schemas via .id() for $ref/$defs

Key Design Decisions

  • Dual type parameters (Schema<Output, Input>) to support transforms where input/output types differ
  • Named schemas (.id()) produce $ref/$defs in JSON Schema; compiler maps these to OpenAPI components/schemas
  • Error aggregation — object/array schemas collect all issues instead of fail-fast
  • Strict TDD — one test at a time, red-green-refactor cycle
  • Written from scratch — no code copied from existing implementation

Test plan

  • Review plan completeness against Zod v4 API surface
  • Verify JSON Schema / OpenAPI output mapping decisions
  • Confirm implementation phase ordering makes sense
  • Validate package structure and file organization

🤖 Generated with Claude Code

viniciusdacal and others added 3 commits February 4, 2026 11:43
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Clarify one-way principle for string formats (no .email()/.uuid() on StringSchema)
- Add s.coerce.date() to coercion section
- Clarify s.record() overloads (single arg vs two args)
- Fix parse flow ordering (refinements before transforms)
- Fix package structure to use proper tree format
- Add detail to phases 6 and 7 (test files, JSON Schema items)
- Add Open Items section (date serialization, brand/readonly JSON Schema, lazy circular refs)
- Remove backward compatibility mention from verification
- Add cross-reference to core API and testing plans
- Remove s.int32() convenience (only s.int())
- Update core API plan: s.string().email/uuid/url() → s.email/uuid/url()

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Resolved as a design decision: DateSchema provides .toISOString() as a
convenience transform (Date → string) for response schemas. JSON Schema
output for s.date() is { type: "string", format: "date-time" }.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@viniciusdacal viniciusdacal merged commit 0e6b71c into main Feb 4, 2026
viniciusdacal added a commit that referenced this pull request Feb 5, 2026
- #4: Define BootSequence contract — ServiceFactory type, example compiler
  output showing JS module with live imports (not JSON manifest)
- #5: Document HEAD (auto-generated from GET) and OPTIONS (handled by CORS)
- #6: Explicitly state no AsyncLocalStorage — services receive request data
  via function arguments only
- #7: Add reserved ctx property names with runtime guard in dev mode
- #8: Clarify testing lives in @vertz/core, packages/testing/ superseded
- #9: Add app.handler getter for edge runtimes with usage examples
- Address deepFreeze concern: skip freeze in production, rely on dev proxy
- Address Object.assign for middleware state accumulation performance
- Address native .env loading: use Node/Bun native support, minimal fallback

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
vertz-tech-lead Bot pushed a commit that referenced this pull request Feb 10, 2026
After investigating the middleware ctx inference gap (issue #137), root
cause was that generic type parameters were defined but never threaded
to the consumer — and no phase owned the end-to-end type flow.

Changes:
- tdd.md: new "Type Flow Verification" section requiring .test-d.ts
  for every generic parameter, end-to-end
- definition-of-done.md: new Phase Done checklist item for type flow
- design-docs.md: new required "Type Flow Map" section (#6) tracing
  types from definition to consumer

Trail: problem (issue #137) → investigation (backstage/research/
process-reviews/core-middleware-gap-analysis.md) → rule change (this
commit)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
vertz-tech-lead Bot added a commit that referenced this pull request Feb 10, 2026
* docs(ui): add @vertz/ui implementation plan

Stage 2 implementation plan for @vertz/ui, covering all 8 phases of
v1.0 scope: compiler foundation, reactivity system, component model,
CSS framework, SSR + hydration, data fetching + forms, routing, and
headless primitives.

Synthesized from the approved design doc, roadmap, and 6 exploration
research documents (CSS framework, codegen impact, animations/flags,
naming, reactive mutations compiler, live streaming feasibility).

Includes architectural decisions table (17 decisions), full package
structure with file trees, integration test acceptance criteria for
every phase, milestone tracking, and runtime size budget.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs(rules): add type flow verification to prevent dead generics

After investigating the middleware ctx inference gap (issue #137), root
cause was that generic type parameters were defined but never threaded
to the consumer — and no phase owned the end-to-end type flow.

Changes:
- tdd.md: new "Type Flow Verification" section requiring .test-d.ts
  for every generic parameter, end-to-end
- definition-of-done.md: new Phase Done checklist item for type flow
- design-docs.md: new required "Type Flow Map" section (#6) tracing
  types from definition to consumer

Trail: problem (issue #137) → investigation (backstage/research/
process-reviews/core-middleware-gap-analysis.md) → rule change (this
commit)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: vertz-tech-lead[bot] <2828099+vertz-tech-lead[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: vertz-tech-lead[bot] <260431879+vertz-tech-lead[bot]@users.noreply.github.com>
vertz-tech-lead Bot pushed a commit that referenced this pull request Feb 11, 2026
- Rename find() to findOne() for clarity (Josh #1)
- Separate read/write visibility: $insert includes .hidden() columns (Josh #2, Ben C3)
- Fix select union type with never-keyed branches for mutual exclusivity (Ben B4)
- Move cache-readiness primitives to v1.1 preview section (PM scope creep)
- Fix Non-Goal #7 to not claim v1 ships cache primitives (PM)
- Add exhaustiveness guarantee for error hierarchy with Assert pattern (Ben B1)
- Add type error quality section with branded error messages (Ben B2)
- Flag d.ref.many().through() as unvalidated, cap depth at 1 (Ben B3)
- Fix E2E type test assertions to match actual type semantics (Josh #3)
- Fix first example to compile under strict mode with ! assertion (Josh #4)
- Add vertz db init onboarding flow (Josh #5)
- Document zero-match behavior for all mutation methods (Josh #8)
- Add SQL injection prevention / parameter binding note (PM minor)
- Add dry-run mode for migrations (PM minor)
- Clarify d.email() is metadata-only, no runtime validation (Josh #6, Ben N4)
- Add vertz.env() pattern for type-safe DATABASE_URL access

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
viniciusdacal pushed a commit that referenced this pull request Feb 11, 2026
* docs(db): add @vertz/db v1 API design plan

Comprehensive design doc for the thin ORM layer covering schema definitions,
type inference, query builder, relations, migrations, error hierarchy,
and metadata-only multi-tenancy markers. Based on approved roadmap,
POC 1 results (28.5% of budget), and all exploration research.

Includes self-review notes from Josh (DX), Ben (feasibility), and PM (scope).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(db-design): address review feedback from Josh, Ben, and PM

- Rename find() to findOne() for clarity (Josh #1)
- Separate read/write visibility: $insert includes .hidden() columns (Josh #2, Ben C3)
- Fix select union type with never-keyed branches for mutual exclusivity (Ben B4)
- Move cache-readiness primitives to v1.1 preview section (PM scope creep)
- Fix Non-Goal #7 to not claim v1 ships cache primitives (PM)
- Add exhaustiveness guarantee for error hierarchy with Assert pattern (Ben B1)
- Add type error quality section with branded error messages (Ben B2)
- Flag d.ref.many().through() as unvalidated, cap depth at 1 (Ben B3)
- Fix E2E type test assertions to match actual type semantics (Josh #3)
- Fix first example to compile under strict mode with ! assertion (Josh #4)
- Add vertz db init onboarding flow (Josh #5)
- Document zero-match behavior for all mutation methods (Josh #8)
- Add SQL injection prevention / parameter binding note (PM minor)
- Add dry-run mode for migrations (PM minor)
- Clarify d.email() is metadata-only, no runtime validation (Josh #6, Ben N4)
- Add vertz.env() pattern for type-safe DATABASE_URL access

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: vertz-tech-lead[bot] <2828099+vertz-tech-lead[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: vertz-dev-dx[bot] <260432280+vertz-dev-dx[bot]@users.noreply.github.com>
vertz-advocate Bot pushed a commit that referenced this pull request Feb 12, 2026
Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions Bot pushed a commit that referenced this pull request Feb 12, 2026
Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions Bot pushed a commit that referenced this pull request Feb 12, 2026
Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
vertz-dev-front Bot pushed a commit that referenced this pull request Feb 12, 2026
Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions Bot pushed a commit that referenced this pull request Feb 12, 2026
Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions Bot pushed a commit that referenced this pull request Feb 12, 2026
Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions Bot pushed a commit that referenced this pull request Feb 12, 2026
Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
viniciusdacal pushed a commit that referenced this pull request Feb 12, 2026
* feat(examples): add task-manager demo app for @vertz/ui v0.1

Build a realistic Task Manager demo exercising every major @vertz/ui
feature end-to-end: reactivity (signal, computed, effect), component
model (ref, onMount, onCleanup, createContext), CSS (css, variants,
defineTheme, ThemeProvider), forms (form with validation), data
fetching (query), routing (defineRoutes, createRouter, createLink),
Dialog and Tabs from @vertz/primitives, and testing with @vertz/ui/test.

Includes DX Journal documenting 8 friction points, 5 gotchas, and
5 wins. Key findings: reactivity system is excellent (9/10),
primitives are production-ready, but no JSX support is a P0 blocker
for developer adoption.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: update bun.lock for task-manager demo dependencies

* refactor(examples): rewrite task-manager demo to JSX

Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs(examples): add F9 friction point — primitives require post-hoc styling

Document that Dialog/Tabs primitives return pre-existing DOM elements
that can't be recreated via JSX, forcing verbose imperative mutation
for className/textContent/data-testid. Recommend accepting optional
style props at creation time.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(examples): add Vite dev server to task-manager demo

Wire up @vertz/ui-compiler Vite plugin so the task-manager example
can be served locally with `bun run dev`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* ci: add examples/ to Dagger SOURCE_PATTERNS

Ensures smart-ci runs the full pipeline when example apps change.
The matching change for .github/workflows/ci.yml requires a token
with workflows permission and will be applied separately.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(ui): add 33 missing CSS shorthand properties and integration test

The token resolver was missing support for many common shorthands that
the task-manager demo relies on: border-r/t, flex-1, flex-col, fixed,
inline-flex, cursor, transition, opacity, z-index, inset, grid-cols,
tracking, uppercase, outline-none, and multi-mode resolution for text
(color vs font-size vs text-align), font (size vs weight), border
(color vs width), and ring (width vs color).

Adds a shorthand coverage integration test that validates every CSS
token used in the demo app resolves without error — 113 test cases.
This prevents future regressions from being discovered at runtime.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(ui): auto-inject CSS at runtime in dev mode

css() now appends <style data-vertz-css> tags to document.head when
running in a browser environment. This ensures component-level styles
are visible without relying on the compiler's production CSS extraction.
Deduplicates by CSS content to avoid repeated injection.

Includes 4 new tests for the injection behavior (happy-dom environment).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(ui): use transition shorthand with per-property timing

transition:colors was outputting timing values into transition-property
(which only accepts property names). Changed to use the transition
shorthand and apply timing to each color property individually.

Also fixed the property mapping from transition-property → transition.

4 new tests for transition resolution.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(demo): add page transitions using View Transitions API

Route changes now use document.startViewTransition() with a
crossfade animation (120ms fade-out, 200ms fade-in). Falls back
to instant swap in browsers without View Transitions support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: vertz-advocate[bot] <2828138+vertz-advocate[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: vertz-dev-front[bot] <2828126+vertz-dev-front[bot]@users.noreply.github.com>
viniciusdacal added a commit that referenced this pull request Feb 22, 2026
docs: @vertz/schema package design plan
viniciusdacal added a commit that referenced this pull request Feb 22, 2026
- #4: Define BootSequence contract — ServiceFactory type, example compiler
  output showing JS module with live imports (not JSON manifest)
- #5: Document HEAD (auto-generated from GET) and OPTIONS (handled by CORS)
- #6: Explicitly state no AsyncLocalStorage — services receive request data
  via function arguments only
- #7: Add reserved ctx property names with runtime guard in dev mode
- #8: Clarify testing lives in @vertz/core, packages/testing/ superseded
- #9: Add app.handler getter for edge runtimes with usage examples
- Address deepFreeze concern: skip freeze in production, rely on dev proxy
- Address Object.assign for middleware state accumulation performance
- Address native .env loading: use Node/Bun native support, minimal fallback

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
viniciusdacal pushed a commit that referenced this pull request Feb 22, 2026
* docs(ui): add @vertz/ui implementation plan

Stage 2 implementation plan for @vertz/ui, covering all 8 phases of
v1.0 scope: compiler foundation, reactivity system, component model,
CSS framework, SSR + hydration, data fetching + forms, routing, and
headless primitives.

Synthesized from the approved design doc, roadmap, and 6 exploration
research documents (CSS framework, codegen impact, animations/flags,
naming, reactive mutations compiler, live streaming feasibility).

Includes architectural decisions table (17 decisions), full package
structure with file trees, integration test acceptance criteria for
every phase, milestone tracking, and runtime size budget.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs(rules): add type flow verification to prevent dead generics

After investigating the middleware ctx inference gap (issue #137), root
cause was that generic type parameters were defined but never threaded
to the consumer — and no phase owned the end-to-end type flow.

Changes:
- tdd.md: new "Type Flow Verification" section requiring .test-d.ts
  for every generic parameter, end-to-end
- definition-of-done.md: new Phase Done checklist item for type flow
- design-docs.md: new required "Type Flow Map" section (#6) tracing
  types from definition to consumer

Trail: problem (issue #137) → investigation (backstage/research/
process-reviews/core-middleware-gap-analysis.md) → rule change (this
commit)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: vertz-tech-lead[bot] <2828099+vertz-tech-lead[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: vertz-tech-lead[bot] <260431879+vertz-tech-lead[bot]@users.noreply.github.com>
viniciusdacal pushed a commit that referenced this pull request Feb 22, 2026
* docs(db): add @vertz/db v1 API design plan

Comprehensive design doc for the thin ORM layer covering schema definitions,
type inference, query builder, relations, migrations, error hierarchy,
and metadata-only multi-tenancy markers. Based on approved roadmap,
POC 1 results (28.5% of budget), and all exploration research.

Includes self-review notes from Josh (DX), Ben (feasibility), and PM (scope).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(db-design): address review feedback from Josh, Ben, and PM

- Rename find() to findOne() for clarity (Josh #1)
- Separate read/write visibility: $insert includes .hidden() columns (Josh #2, Ben C3)
- Fix select union type with never-keyed branches for mutual exclusivity (Ben B4)
- Move cache-readiness primitives to v1.1 preview section (PM scope creep)
- Fix Non-Goal #7 to not claim v1 ships cache primitives (PM)
- Add exhaustiveness guarantee for error hierarchy with Assert pattern (Ben B1)
- Add type error quality section with branded error messages (Ben B2)
- Flag d.ref.many().through() as unvalidated, cap depth at 1 (Ben B3)
- Fix E2E type test assertions to match actual type semantics (Josh #3)
- Fix first example to compile under strict mode with ! assertion (Josh #4)
- Add vertz db init onboarding flow (Josh #5)
- Document zero-match behavior for all mutation methods (Josh #8)
- Add SQL injection prevention / parameter binding note (PM minor)
- Add dry-run mode for migrations (PM minor)
- Clarify d.email() is metadata-only, no runtime validation (Josh #6, Ben N4)
- Add vertz.env() pattern for type-safe DATABASE_URL access

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: vertz-tech-lead[bot] <2828099+vertz-tech-lead[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: vertz-dev-dx[bot] <260432280+vertz-dev-dx[bot]@users.noreply.github.com>
viniciusdacal pushed a commit that referenced this pull request Feb 22, 2026
* feat(examples): add task-manager demo app for @vertz/ui v0.1

Build a realistic Task Manager demo exercising every major @vertz/ui
feature end-to-end: reactivity (signal, computed, effect), component
model (ref, onMount, onCleanup, createContext), CSS (css, variants,
defineTheme, ThemeProvider), forms (form with validation), data
fetching (query), routing (defineRoutes, createRouter, createLink),
Dialog and Tabs from @vertz/primitives, and testing with @vertz/ui/test.

Includes DX Journal documenting 8 friction points, 5 gotchas, and
5 wins. Key findings: reactivity system is excellent (9/10),
primitives are production-ready, but no JSX support is a P0 blocker
for developer adoption.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: update bun.lock for task-manager demo dependencies

* refactor(examples): rewrite task-manager demo to JSX

Convert all 8 component/page files from manual DOM construction (.ts)
to declarative JSX (.tsx), demonstrating the @vertz/ui-compiler's
first-class JSX support that was missing from the original demo.

Changes:
- Rename 8 files from .ts to .tsx (app, task-card, task-form,
  confirm-dialog, task-list, task-detail, create-task, settings)
- Replace document.createElement/appendChild chains with JSX
- Add tsconfig JSX settings (react-jsx with custom jsxImportSource)
- Add jsx.d.ts type definitions and jsx-runtime.ts for Bun tests
- Update DX_JOURNAL.md: resolve F1 (JSX exists), add Win #6,
  raise DX score from 5/10 to 7.5/10

Primitives (Dialog, Tabs) keep imperative creation since they return
pre-wired ARIA element objects, with JSX used for surrounding layout.

Net result: ~100 fewer lines, dramatically cleaner authoring DX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs(examples): add F9 friction point — primitives require post-hoc styling

Document that Dialog/Tabs primitives return pre-existing DOM elements
that can't be recreated via JSX, forcing verbose imperative mutation
for className/textContent/data-testid. Recommend accepting optional
style props at creation time.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(examples): add Vite dev server to task-manager demo

Wire up @vertz/ui-compiler Vite plugin so the task-manager example
can be served locally with `bun run dev`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* ci: add examples/ to Dagger SOURCE_PATTERNS

Ensures smart-ci runs the full pipeline when example apps change.
The matching change for .github/workflows/ci.yml requires a token
with workflows permission and will be applied separately.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(ui): add 33 missing CSS shorthand properties and integration test

The token resolver was missing support for many common shorthands that
the task-manager demo relies on: border-r/t, flex-1, flex-col, fixed,
inline-flex, cursor, transition, opacity, z-index, inset, grid-cols,
tracking, uppercase, outline-none, and multi-mode resolution for text
(color vs font-size vs text-align), font (size vs weight), border
(color vs width), and ring (width vs color).

Adds a shorthand coverage integration test that validates every CSS
token used in the demo app resolves without error — 113 test cases.
This prevents future regressions from being discovered at runtime.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(ui): auto-inject CSS at runtime in dev mode

css() now appends <style data-vertz-css> tags to document.head when
running in a browser environment. This ensures component-level styles
are visible without relying on the compiler's production CSS extraction.
Deduplicates by CSS content to avoid repeated injection.

Includes 4 new tests for the injection behavior (happy-dom environment).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(ui): use transition shorthand with per-property timing

transition:colors was outputting timing values into transition-property
(which only accepts property names). Changed to use the transition
shorthand and apply timing to each color property individually.

Also fixed the property mapping from transition-property → transition.

4 new tests for transition resolution.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(demo): add page transitions using View Transitions API

Route changes now use document.startViewTransition() with a
crossfade animation (120ms fade-out, 200ms fade-in). Falls back
to instant swap in browsers without View Transitions support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: vertz-advocate[bot] <2828138+vertz-advocate[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: vertz-dev-front[bot] <2828126+vertz-dev-front[bot]@users.noreply.github.com>
@viniciusdacal viniciusdacal deleted the docs/schema-design branch February 22, 2026 16:20
viniciusdacal added a commit that referenced this pull request Apr 5, 2026
…2053)

Phase 1 of runtime feature parity tests:
- Test skeleton: main.rs, common.rs (shared helpers), checklist_meta.rs (report validation)
- HTTP serving tests: API delegation (#5), proxy rules (#6), logging middleware (#7)
- Compilation tests: import.meta.env (#19), CSS→JS (#20), tsconfig paths (#22),
  /@deps endpoint (#23), /@css endpoint (#24), theme CSS injection (#25)
- PARITY_REPORT.md with all 55 included + 12 deferred feature rows
- Test fixtures: env-app, css-app, tsconfig-paths-app, theme-app

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
viniciusdacal added a commit that referenced this pull request Apr 5, 2026
* test(runtime): add Phase 1 parity tests — infra, HTTP, compilation (#2053)

Phase 1 of runtime feature parity tests:
- Test skeleton: main.rs, common.rs (shared helpers), checklist_meta.rs (report validation)
- HTTP serving tests: API delegation (#5), proxy rules (#6), logging middleware (#7)
- Compilation tests: import.meta.env (#19), CSS→JS (#20), tsconfig paths (#22),
  /@deps endpoint (#23), /@css endpoint (#24), theme CSS injection (#25)
- PARITY_REPORT.md with all 55 included + 12 deferred feature rows
- Test fixtures: env-app, css-app, tsconfig-paths-app, theme-app

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test(runtime): add Phase 2 parity tests — SSR, HMR, watcher, module graph (#2053)

Phase 2 of runtime feature parity tests:
- SSR: verify SSR-enabled server serves HTML shell for page routes (#34)
- HMR Tier 1: WebSocket update message delivery via hmr_hub.broadcast (#37)
- HMR Tier 1: CSS-only update message (not full-reload) (#38)
- HMR Tier 2: FileWatcher detects entry file changes in tempdir (#39)
- Module graph: transitive dependency invalidation A→B→C (#40)
- Shared helpers: copy_fixture() for tempdir-based watcher tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test(runtime): add Phase 3 parity tests — errors, diagnostics, MCP, auto features (#2053)

Phase 3 of runtime feature parity tests:
- Error overlay: client error reporting via POST endpoint (#47)
- Console log: ring buffer endpoint returns stored entries (#50)
- MCP: Streamable HTTP responds to tools/list with 7 registered tools (#51)
- MCP: tool invocation returns diagnostics result (#52)
- MCP: events WebSocket delivers initial server status (#53)
- Auto-install: blacklist/dedup coordination logic (#54)
- Dep watcher: detects file changes in linked package dist/ (#55)

All 22 parity tests passing. Full cargo test --all clean. Clippy clean.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(runtime): address review findings in parity tests (#2053)

- Fix ~25 incorrect EXISTING test location references in PARITY_REPORT.md
  to match actual function names in static_serving.rs, client_render.rs,
  ssr_render.rs, and error_overlay.rs
- Rename misleading ssr_redirect_returns_302_with_location_header to
  ssr_enabled_server_returns_html_shell_for_page_routes (test asserts 200,
  not 302)
- Add import.meta.env.SECRET_KEY reference to env-app fixture so the
  non-public env var assertion actually validates the code path

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant