ecs: order on System.render, typed input, importer's copy of the runtime, faster first tick (0.1.1)

.github/workflows/ci.yml

@@ -50,5 +50,8 @@ jobs:
       - name: Build (every package, topological)
         run: pnpm -r run build
 
+      - name: API docs (every package that defines them; warnings fail)
+        run: pnpm -r run docs
+
       - name: Test (each package runs its own complete suite)
         run: pnpm -r run test

.github/workflows/deploy-docs.yml

@@ -31,36 +31,20 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - run: pnpm run build
-        working-directory: packages/data
+      - run: pnpm -r run build
 
-      - run: cp -r packages/data/dist packages/data/docs/dist
+      - run: pnpm -r run docs
 
-      - run: pnpm --filter @adobe/data-sync build
-
-      - run: pnpm --filter @adobe/data-lit build
-
-      - run: pnpm --filter @adobe/data-gpu build
-
-      - run: pnpm --filter data-p2p-tictactoe build
-        env:
-          CI: true
-
-      - run: cp -r packages/data-p2p-tictactoe/dist packages/data/docs/p2p-tictactoe
-
-      - run: pnpm --filter data-gpu-samples build
-        env:
-          CI: true
-
-      - run: cp -r packages/data-gpu-samples/dist packages/data/docs/gpu-samples
+      # Each package's package.json `pages` field says what it publishes where.
+      - run: node scripts/collect-pages.mjs site
 
       - uses: actions/configure-pages@v5
         with:
           enablement: true
 
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: packages/data/docs
+          path: site
 
   deploy:
     needs: build

.gitignore

@@ -47,10 +47,12 @@ source.txt
 # Generated Docs (typedoc output)
 docs/api
 packages/data/docs/api
+packages/ecs/docs
 packages/data/references
 
 # Playwright MCP capture artifacts
 .playwright-mcp/
 
 # Vitest browser attachments and failure screenshots
 .vitest/
+/site/

CLAUDE.md

@@ -27,6 +27,12 @@ Standard script names a package may define:
   that the uniform pipeline does not call.
 - **`lint`** — lint the package.
 - **`dev`** — local dev/watch.
+- **`docs`** — generate the package's documentation (e.g. typedoc). What a
+  package publishes to the GitHub Pages site is its `pages` field: a list of
+  `{ "from", "to" }`, a folder of the package and its path on the site (`"."`
+  for the root). The docs workflow runs `pnpm -r run build` and
+  `pnpm -r run docs`, then `scripts/collect-pages.mjs` copies every package's
+  `pages`, so publishing never names a package.
 
 Do **not** add a `publish-public` (or similar) script. Publishing is governed
 *only* by the `private` field: `pnpm -r publish` publishes every package with

packages/data-gpu-samples/package.json

@@ -4,6 +4,9 @@
   "description": "WebGPU samples built on @adobe/data-gpu",
   "type": "module",
   "private": true,
+  "pages": [
+    { "from": "dist", "to": "gpu-samples" }
+  ],
   "scripts": {
     "predev": "pnpm --filter @adobe/data-gpu build",
     "dev": "vite",

packages/data-gpu-samples/vite.config.ts

@@ -14,9 +14,9 @@ export default defineConfig({
     },
   },
   root: ".",
-  // In production (GitHub Pages) the app lives at /data/graphics-samples/.
+  // In production (GitHub Pages) the app lives at /data/gpu-samples/, its `pages` target.
   // The dev server ignores this — it always serves from /.
-  base: process.env.CI ? "/data/graphics-samples/" : "/",
+  base: process.env.CI ? "/data/gpu-samples/" : "/",
   build: { outDir: "dist" },
   server: { port: 3008, open: false },
 });

packages/data-p2p-tictactoe/package.json

@@ -4,6 +4,9 @@
   "description": "Serverless P2P tic-tac-toe — WebRTC DataChannel + @adobe/data-sync",
   "type": "module",
   "private": true,
+  "pages": [
+    { "from": "dist", "to": "p2p-tictactoe" }
+  ],
   "scripts": {
     "dev": "vite",
     "build": "vite build",

packages/data/docs/index.html

@@ -16,6 +16,7 @@ <h1>@adobe/data</h1>
     <ul>
         <li><a href="./api/">API Reference</a></li>
         <li><a href="./api/modules/observe.html">Observable API</a></li>
+        <li><a href="./ecs/">@adobe/ecs API Reference</a></li>
         <li><a href="./perftest.html">ECS Performance Test</a></li>
         <li><a href="https://github.com/adobe/data">Source on GitHub</a></li>
     </ul>

packages/data/package.json

@@ -5,6 +5,10 @@
   "type": "module",
   "sideEffects": false,
   "private": false,
+  "pages": [
+    { "from": "docs", "to": "." },
+    { "from": "dist", "to": "dist" }
+  ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -19,8 +23,8 @@
   "scripts": {
     "build": "pnpm build-assembly && run-p build:*",
     "build:code": "tsc -b",
-    "build:apidocs": "typedoc",
     "typecheck": "pnpm build-assembly && tsc -b",
+    "docs": "typedoc",
     "build-assembly": "run-p asbuild:release",
     "clean": "rm -rf dist build node_modules",
     "clean-cache": "rm -rf node_modules/.cache",

packages/ecs/CLAUDE.md

@@ -25,7 +25,8 @@ Humans own the interface and agents own the implementation: agents don't add to
   It's a project of its own: nothing in it imports from outside it. Each type exists once, there.
 - **`src/implementation`** holds `createWorld` and everything behind it, the kernel compiler included. It imports
   types and the registry's read side from `src/interface`.
-- **`src/samples`** holds one folder per sample, its page included; `pnpm sample` serves them.
+- **`src/samples`** holds one folder per sample, its page included. `pnpm dev` (or `pnpm sample`, without
+  the type-check watch) serves them, with a sample browser at the root that has a tab for each.
 - `src/index.ts` exports `src/interface`, and `World` as a value too, whose `create` and `join` are the
   implementation's, so `import { World } from "@adobe/ecs"` gives consumers the type, `World.create` and `World.join`,
   the only entry points. Samples and the guide use them; tests and benchmarks may take `createWorld` from
@@ -44,6 +45,12 @@ when a measured win conflicts with a style or design preference, take the win an
 row as low as it can be, and allocate nothing on those paths: reuse arrays, buffers and objects, share read-only
 empties, and avoid closures, spreads and awaits there. Measure changes with `pnpm perf` against the recorded baseline.
 
+## Pull requests
+
+Each PR costs a review, a merge and a publish, so keep one open PR at a time. Add new work and fixes to it as more
+commits; never open stacked or parallel PRs. Keep it rebased on main, with this package's version one above main's.
+Bump it by hand in `package.json`; never run the workspace `bump` script, which bumps packages this PR didn't change.
+
 ## Memory
 
 Decisions about working on this package live in `memory.md`; add new ones there.

packages/ecs/README.md

@@ -1,5 +1,54 @@
 # @adobe/ecs
 
-A data-oriented entity component system. Systems run on the main thread, on worker threads, as WASM kernels or on the GPU.
+A high-performance, multithreaded Entity Component System for web-based applications, simulations and games.
 
-See the [guide](src/guide/guide.md) for how to use it.
+## Features
+
+- **Linear, gapless structure-of-arrays component storage**
+  - Fixed-length values (numbers, tuples, structs) in a `SharedArrayBuffer`
+    - Shared across the main thread and all workers
+    - Read by WASM kernels without copying
+    - WebGPU-compatible struct layout for fast uploads
+  - WebGPU storage for GPU system kernels
+    - Synced back to shared memory only when the CPU reads it
+  - Strings in shared memory, readable on every thread
+  - Objects and other variable-length values on the thread that owns them
+- **Declarations**
+  - Components and resources declared once, as TypeScript types; the build registers them
+  - Named types such as `F32`, `U32` and your own `Schema.Type`s give storage precision, width and bounds
+- **Systems**
+  - Plain TypeScript bodies with declared reads and writes
+  - Kernels compiled and checked at build time to optimized JavaScript, WASM and WGSL
+  - Balanced scheduling across the main thread, workers and the GPU
+  - Typed input, with its schema generated from the TypeScript type
+  - Render systems that draw straight from component storage
+  - Observer systems for reading state into a UI
+- **Changes**
+  - Per-component added and changed ticks: an O(1) check per entity, with each change seen exactly once
+  - Filters that skip unchanged chunks and 64-row blocks
+  - Structural changes batched at sync points, so memory never moves while systems run
+  - Rules, finalizers and traits for derived components, cleanup and references
+- **Queries**
+  - Hash, unique, sorted and keyless indexes, all updated incrementally
+  - Hierarchy traversal that reruns only below what changed
+- **Threads**
+  - Worlds shared with other threads through a `MessagePort` or worker
+  - Joined threads run their own systems and observers, and lend their workers to the pool
+- **Runtime**
+  - Kernels allocate nothing per row; commands, lookups and reports reuse their buffers
+  - Errors reported as data, in each run's report
+
+## Setup
+
+```ts
+// vite.config.ts
+import { Compiler } from "@adobe/ecs/compiler";
+export default defineConfig({ plugins: [Compiler.plugin()] });
+```
+
+A library builds with `Compiler.plugin({ library: true })`, so its build ships the registrations its declarations give.
+
+## Guide
+
+See the [guide](src/guide/guide.md) for how to use it, and the [API reference](https://adobe.github.io/data/ecs/) for
+every type and function.