# WebkitJS condensed documentation

Canonical documentation: https://webkitjs.com/

WebkitJS is a from-scratch browser framework and native toolchain. Its authoring language is Adaptive Platform JSX (`.apx`), a TypeScript-shaped JSX dialect with WebkitJS semantics. Components are plain setup functions that execute exactly once. Fine-grained reactive state updates specific real-DOM text nodes, properties, attributes, and collections without a virtual DOM, diff pass, hook system, or component re-render.

## Mental model

1. A component function runs once and returns real DOM nodes.
2. `state`, `derived`, and `effect` build a fine-grained reactive graph.
3. Passing an accessor keeps a value live. Calling it during setup takes a snapshot.
4. The compiler lowers APX into template cloning, path-addressed bindings, package-aware tree shaking, and hardened JavaScript.
5. The runtime batches writes and disposes reactive ownership when UI leaves the document.

```apx
import { render, state } from "@webkitjs/foundation";
import { Button } from "@webkitjs/componentkit";

const count = state(0);

const Counter = () => (
  <main>
    <h1>Counter</h1>
    <output aria-live="polite">{count}</output>
    <Button onClick={() => count.update((value) => value + 1)}>
      Increment
    </Button>
  </main>
);

const app = document.querySelector<HTMLElement>("#app");
if (!app) throw new Error("Missing #app root.");
render(Counter, app);
```

`{count}` binds reactively. `{count()}` reads the current number once. WebkitJS uses real DOM names: `class`, `for`, lowercase attributes, `onClick`, and real `Node` values. Do not use React hooks, `className`, virtual nodes, or component re-render assumptions.

## Core packages

- `@webkitjs/foundation`: state, derived values, effects, ownership, rendering, collections, routing, adaptive experiences, stores, IndexedDB, networking, channels, and browser transports.
- `@webkitjs/stylekit`: semantic tokens, light/dark themes, `DesignLanguage`, `css`, keyframes, intents, materials, and visual adapters.
- `@webkitjs/symbolkit`: `SFSymbol` for the registered quick set plus generated category exports for the full SF-compatible catalog.
- `@webkitjs/componentkit`: controls, navigation, forms, lists, tables, overlays, status, charts, media, and application surfaces.
- `@webkitjs/canvas`: authored layout and presentation sections for product composition.
- `@webkitjs/intelligence`: verified component, pattern, design, and build guidance for agents and tooling.

Dependencies point downward. Foundation has no package dependency. Browser libraries do not import Node APIs or npm packages.

## Reactivity

```apx
const first = state("Ada");
const last = state("Lovelace");
const fullName = derived(() => `${first()} ${last()}`);

effect(() => {
  document.title = fullName();
});

batch(() => {
  first.set("Grace");
  last.set("Hopper");
});
```

- `state(value)` returns an accessor with `set`, `update`, and `peek`.
- `derived(fn)` is lazy, memoized, and dependency-tracked.
- `effect(fn)` runs side effects and automatically tracks reads.
- `batch(fn)` coalesces propagation.
- `untrack(fn)` reads without subscribing.
- `onCleanup(fn)` binds cleanup to the current owner or effect run.

Collections use keyed reconciliation. When the compiler proves a homogeneous row shape, it can lower ordinary collection code to column-indexed storage and direct DOM writers without changing the authoring surface.

## Components and rendering

Components are const-arrow functions. Intrinsic APX compiles to hoisted templates and targeted bindings. Components and fragments are semantic boundaries rather than virtual nodes.

Use componentkit for interactive roles: `Button`, `TextField`, `Toggle`, `Form`, `FormField`, `Menu`, `Dialog`, `Sheet`, `Popover`, `Sidebar`, `NavigationBar`, `TabBar`, `List`, `Table`, `SettingsList`, `Notification`, `ProgressBar`, `Skeleton`, and the verified chart/media surfaces. Semantic APX is appropriate for headings, copy, media, and project-specific composition.

## Adaptive experiences

`Experience` establishes the application shell and device information. Phone, tablet, and desktop can use different navigation or layout trees while sharing domain state. CSS can adapt through the experience classes on the document. Prefer intent-level adaptation over squeezing a desktop grid onto a phone.

```apx
import { Experience, Phone, Tablet, Desktop } from "@webkitjs/foundation";

const App = () => (
  <Experience>
    <Phone><CompactWorkspace /></Phone>
    <Tablet><SplitWorkspace /></Tablet>
    <Desktop><FullWorkspace /></Desktop>
  </Experience>
);
```

## Styling

Stylekit owns semantic tokens and appearance. Define a project-specific `DesignLanguage`, apply it once, and compose styles with tokens rather than literal framework-internal values. Keep light and dark values paired. Respect reduced motion, contrast, touch targets, and logical CSS properties.

Use generated `css()` classes for component styles. A visual adapter changes a component's visual surface; it is not a replacement for reactive DOM attribute binding.

## Routing and code splitting

The foundation router uses path routes and real browser history. Page components can be split with `importAsync(() => import("./page"))`; inactive pages are not fetched. Keep the root entry thin, route ownership in a dedicated module, and one major screen per module.

## Native CLI

WebkitJS is distributed as one native `webkitjs` command.

```sh
webkitjs init --dir my-app --form application
cd my-app
webkitjs check
webkitjs build
webkitjs start
```

Important commands:

- `webkitjs init`: scaffold a manifest-owned project and first screen.
- `webkitjs check`: parse and check APX project imports, exports, bindings, architecture, and framework reuse.
- `webkitjs build`: emit a hardened, minified, deployable distribution.
- `webkitjs start`: foreground development server with framework-aware HMR.
- `webkitjs preview`: foreground hardened production preview for performance measurement.
- `webkitjs pkg build|verify`: build and verify content-addressed compiled packages.
- `webkitjs lsp`: APX diagnostics, hover, definition, and completion over stdio.
- `webkitjs agent context`: provision verified package intelligence and aggregate it for any agent.
- `webkitjs agent serve`: expose verified intelligence, lookup, check, and build through MCP stdio.

Always resolve blocking `WK` diagnostics. Advisory diagnostics remain legal APX but identify framework reuse, design-contract, or source-architecture gaps.

## Project shape

One application owns one `webkit.pkg.json`, one `webkit_packages/` tree, and its source/assets/output directories.

```text
src/main.apx                  bootstrap and render only
src/app.apx                   Experience, shared shell, route ownership
src/screens/*.screen.apx      routed or major views
src/components/*.component.apx reusable view pieces
src/features/<feature>/       feature-owned UI, state, data, actions
src/shared/                   pure shared logic
```

Every relative import is a source-graph promise. Create or move the exact target in the same change. Do not create a second manifest at a monorepo ancestor.

## Packages and intelligence

First-party packages ship as verified compiled `lib.wkpkg` containers with package-level intelligence. The CLI provisions built-ins into a project when needed. A package consumer receives name checking, definitions, public documentation, and tree shaking without raw package source.

Before agent-authored implementation, consume the complete verified intelligence, publish a project map, map UI roles to exact exports, define an art-direction contract, and verify static plus rendered behavior. WebkitJS supplies framework knowledge, not authorization; repository approval remains the host guardrail's responsibility.

## MCP

The local MCP server is stdio-only and runs inside a manifest-owned project:

```json
{
  "mcpServers": {
    "webkitjs": {
      "command": "webkitjs",
      "args": ["agent", "serve", "--root", "."]
    }
  }
}
```

The service provides ordered verified intelligence delivery, status, lookup, check, and build. It never edits agent-authority files or approves repository actions. See https://webkitjs.com/mcp.json for the copyable configuration.

## Server boundary

WebkitJS Server is a separate product. Client `.apx`/`.ts` and server `.apxs`/`.apts` modules are disjoint. A server target declares typed `endpoint({...})` exports using the `s.*` schema builder. The compiler emits bytecode, endpoint metadata, and a generated typed client stub; client code calls only that stub.

The server dialect has no DOM, `window`, browser globals, JSX, or browser `fetch`. Runtime capabilities are available only through handler context: identity, configured databases, uploads, responses, and SSE streams. Production sealing, signing, deployment, mesh identity, and execution belong to the separate `webkitjs-server` binary.

Webkitjs.com is a documentation website, not a hosted application API, so it intentionally publishes no `openapi.json`. Individual WebkitJS applications generate and own their endpoint contracts.

## Executable example

Download the project at https://webkitjs.com/examples/counter/ and run:

```sh
webkitjs check --dir examples/counter
cd examples/counter
webkitjs build
webkitjs preview
```

Additional reference pages:

- https://webkitjs.com/foundation
- https://webkitjs.com/components
- https://webkitjs.com/patterns
- https://webkitjs.com/styling
- https://webkitjs.com/development
- https://webkitjs.com/development/intelligence
- https://webkitjs.com/server