# KitJS roadmap

KitJS is a CDN-first browser package for adding scoped reactivity to ordinary
HTML. It grows by making that small contract easier to use and more reliable,
not by accumulating framework features.

The package remains:

- HTML-first and dependency-free at runtime;
- usable without a frontend build step;
- split into one default Kit profile and one optional Hydrate profile;
- limited to shallow local state, declarative bindings, direct client
  components, and compatibility-checked navigation; and
- explicit about native browser fallback whenever Hydrate cannot preserve a
  document safely.

## Stable baseline: `1.0.0`

`1.0.0` is the stable standalone package contract. Its publication gate binds
one tagged commit to the npm tarball, exact jsDelivr/unpkg files, npm `latest`,
and both default unversioned CDN entry points. Exact public evidence is
recorded in `RELEASE_READINESS.md` only after retrieval succeeds.

The stable contract includes the ordinary-element form of `data-kit-if`:

- use `data-kit-if` directly on one element for the common one-root branch;
- use `<template data-kit-if>` for inert-first content, multiple siblings, or
  wrapper-free fragments;
- keep `data-kit-for` and `data-kit-key` template-only;
- read a direct condition from its enclosing boundary, not from a scope or
  component declared on the conditional element itself;
- retain the exact authored host when the initial condition is true; and
- create fresh DOM/component identity only after a false unmount followed by a
  true remount.

Client-side conditions are presentation behavior, not authorization or a
secrecy boundary. Ordinary direct DOM may paint or start resources before the
runtime prepares it; use an inert template when that distinction matters.

The deterministic artifacts are 206,607 bytes for Kit and 314,424 bytes for
Hydrate. Exact hashes, CI runs, tarball identity, CDN verification, and
provenance evidence are recorded in `RELEASE_READINESS.md`.

## 1.0 priorities

### CDN usability

- Keep the first example copy-pasteable with one exact-version jsDelivr URL,
  canonical SRI, and no build instructions.
- Keep Kit as the default profile and explain Hydrate as an explicit choice for
  same-origin navigation continuity.
- Make inline-script fallback unmistakable: inline executable scripts are
  valid with Kit, while Hydrate leaves navigation native when executable
  topology is incompatible.
- Keep direct client components unversioned and document that missing
  definitions neither fetch code nor reload the page.
- Keep deployment guidance for immutable URLs, SRI, caching, CSP, and subpath
  hosting concise and verifiable.

### Browser compatibility

- Continue the deep Chromium corpus and the shared critical
  Chromium/Firefox/WebKit matrix for both exact profiles.
- Report browser engine and version evidence precisely; do not treat a WebKit
  run as a blanket Safari support claim.
- Extend adversarial parser, DOM ownership, form, focus, history, fragment, and
  native-fallback coverage whenever a browser difference is found.
- Preserve fail-closed expression and resource budgets.

### Accessibility

- Test keyboard activation and focus restoration across conditional branches,
  keyed rows, and Hydrate navigation.
- Add examples that preserve semantic HTML, labels, live-region behavior, and
  native form submission fallback.
- Document how `data-kit-show`, `hidden`, bound ARIA attributes, and component
  lifecycle affect assistive technology.

### Documentation

- Keep the README focused on CDN onboarding and common directives.
- Keep `KITJS_SPEC.md` normative for the standalone browser package.
- Keep the Vietnamese guide behaviorally aligned with the English guide.
- Add small runnable examples before expanding prose.
- Keep release availability, support, and migration claims tied to exact
  public evidence.

### Performance and diagnostics

- Use deterministic work-count assertions for release gates where possible.
- Keep benchmark timings descriptive, machine-local, and free of universal
  pass/fail thresholds.
- Improve actionable errors for invalid expressions, missing client component
  definitions, unsafe bindings, and Hydrate topology fallback.
- Reduce repeated traversal or allocation only when browser conformance proves
  unchanged behavior.

## Historical baselines

`1.0.0-rc.1` remains immutable historical evidence. Its verified Kit and
Hydrate files are 203,061 and 310,808 bytes respectively, and it requires
`<template data-kit-if>`.

`0.9.0-next.15` remains the verified migration predecessor. Its verified Kit
and Hydrate files are 203,492 and 311,181 bytes respectively. That old artifact
accepted the split `data-kit-version` attribute as deprecated compatibility
input; the 1.0 contract rejects it. There is no `data-kit-local` directive.

Historical artifacts never gain behavior from a later release. Their exact
commits, hashes, tarballs, runs, and public retrieval evidence remain in
`RELEASE_READINESS.md`.

## Stable `1.0.0` release gate

A stable release is valid only when all of the following hold against one
unchanged commit and its exact artifacts:

1. Deterministic build, source/dist parity, package contract, complete browser
   corpus, required browser matrix, release-verifier tests, and benchmark smoke
   all pass without a required skip.
2. The packaged static example passes reactive behavior, component lifecycle,
   compatible Hydrate navigation, history/focus/forms, and intentional native
   fallback from a clean checkout.
3. README, browser specification, Vietnamese guide, deployment guide, support
   policy, security policy, and release evidence agree on the standalone CDN
   contract.
4. The exact npm tarball, clean install, jsDelivr files, and unpkg files match
   the tagged artifacts; signatures and provenance are independently checked.
5. No known release blocker remains. Any runtime-byte or normative-contract
   change advances the candidate identity and reruns the full evidence cycle.

A plain `1.0.0` is published directly to npm `latest`. The same workflow then
verifies the immutable package and exact CDN bytes, signature/provenance, npm
`latest`, and the default unversioned jsDelivr/unpkg entry points. Prereleases
remain isolated on npm `next`.

## After stable `1.0`

- Improve CDN examples, diagnostics, accessibility guidance, and browser
  compatibility before considering new authored syntax.
- Publish additional static-site examples for common forms, lists, dialogs,
  and navigation patterns.
- Continue bounded performance work backed by reproducible browser evidence.
- Consider new directives only when existing HTML, directives, and direct
  components cannot express the use case clearly.
- Keep virtual DOMs, deep-reactivity systems, runtime package discovery, and a
  public manual renderer outside the package contract.