@kumikijs/compiler 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,34 +1,34 @@
-# @kumikijs/compiler
-
-Kumiki compiler — lexer, parser, typechecker, and code generator. Part of [Kumiki](https://github.com/kage1020/Kumiki), an AI-first web framework language.
-
-## Install
-
-```sh
-npm i @kumikijs/compiler
-```
-
-## Usage
-
-```ts
-import { check, compile, lex, parse } from "@kumikijs/compiler";
-
-// Type-check a .kumiki source (returns diagnostics)
-const diagnostics = check(source);
-
-// Compile a source into a runnable HTML app
-const result = compile(source);
-```
-
-To inline the runtime bundle from disk in a Node environment, use the `./node` subpath:
-
-```ts
-import { compile } from "@kumikijs/compiler";
-import { nodeRuntimeBundleReader } from "@kumikijs/compiler/node";
-
-const result = compile(source, { bundle: true, readRuntimeBundle: nodeRuntimeBundleReader });
-```
-
-## License
-
-Apache-2.0
+# @kumikijs/compiler
+
+Kumiki compiler — lexer, parser, typechecker, and code generator. Part of [Kumiki](https://github.com/kage1020/Kumiki), an AI-first web framework language.
+
+## Install
+
+```sh
+npm i @kumikijs/compiler
+```
+
+## Usage
+
+```ts
+import { check, compile, lex, parse } from "@kumikijs/compiler";
+
+// Type-check a .kumiki source (returns diagnostics)
+const diagnostics = check(source);
+
+// Compile a source into a runnable HTML app
+const result = compile(source);
+```
+
+To inline the runtime bundle from disk in a Node environment, use the `./node` subpath:
+
+```ts
+import { compile } from "@kumikijs/compiler";
+import { nodeRuntimeBundleReader } from "@kumikijs/compiler/node";
+
+const result = compile(source, { bundle: true, readRuntimeBundle: nodeRuntimeBundleReader });
+```
+
+## License
+
+Apache-2.0

package/dist/capabilities-Bdub5oAe.js

@@ -0,0 +1,75 @@
+//#region src/capabilities.ts
+/** Capabilities that may appear in `app.caps` without any manifest. */
+const STANDARD_CAPABILITIES = new Set([
+	"http.get",
+	"http.post",
+	"http.put",
+	"http.patch",
+	"http.delete",
+	"storage.read",
+	"storage.write",
+	"session.read",
+	"session.write",
+	"indexed.read",
+	"indexed.write",
+	"nav.push",
+	"nav.replace",
+	"nav.back",
+	"clipboard.read",
+	"clipboard.write",
+	"notification.show",
+	"analytics.send",
+	"log.write",
+	"crypto.random",
+	"crypto.hash",
+	"media.camera",
+	"media.microphone",
+	"geo.read",
+	"socket.connect",
+	"socket.send"
+]);
+/** A capability name must look like `group.action` (lowercase, dot-separated). */
+const CAP_NAME = /^[a-z][a-z0-9]*\.[a-z][a-z0-9-]*$/;
+/**
+* Validate a parsed `kumiki.caps.json` value. Accepts either bare strings or
+* `{ name, description? }` objects in the `capabilities` array. Pure — the
+* caller does the file read + JSON parse and reports the location.
+*/
+function parseCapabilityManifest(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		error: "manifest must be a JSON object"
+	};
+	const caps = raw.capabilities;
+	if (!Array.isArray(caps)) return {
+		ok: false,
+		error: "\"capabilities\" must be an array"
+	};
+	const names = [];
+	for (let i = 0; i < caps.length; i++) {
+		const entry = caps[i];
+		const name = typeof entry === "string" ? entry : pickName(entry);
+		if (typeof name !== "string" || name.length === 0) return {
+			ok: false,
+			error: `capabilities[${i}] must be a string or an object with a non-empty "name"`
+		};
+		if (!CAP_NAME.test(name)) return {
+			ok: false,
+			error: `capability "${name}" must look like "group.action" (lowercase, dot-separated)`
+		};
+		if (STANDARD_CAPABILITIES.has(name)) return {
+			ok: false,
+			error: `capability "${name}" is already a standard capability — remove it from the manifest`
+		};
+		names.push(name);
+	}
+	return {
+		ok: true,
+		manifest: { capabilities: names }
+	};
+}
+function pickName(entry) {
+	if (typeof entry === "object" && entry !== null) return entry.name;
+}
+//#endregion
+export { parseCapabilityManifest as n, STANDARD_CAPABILITIES as t };

package/dist/index.d.ts

@@ -31,7 +31,16 @@ type Program = {
   kind: "Program";
   defs: Def[];
 };
-type Def = TypeDef | SlotDef | ReducerDef | TileDef | FnDef | EffectDef | AppDef | ThemeDef;
+type Def = TypeDef | SlotDef | ReducerDef | TileDef | FnDef | EffectDef | AppDef | ThemeDef | MotionDef | TestDef;
+type TestDef = {
+  kind: "TestDef";
+  name: string; /** `reducer-test` targets a reducer name; `tile-test` targets a tile name. */
+  testKind: "reducer-test" | "tile-test";
+  target: string; /** The `given = { ... }` record literal (interpreted, not codegen'd as-is). */
+  given: Expr; /** `expect = { slots, effects }` / `{ panic }` (record) for reducer-test; a tile expression for tile-test. */
+  expect: Expr | TileExpr;
+  pos: Pos;
+};
 type ThemeValue = string | number | {
   [k: string]: ThemeValue;
 };
@@ -43,6 +52,14 @@ type ThemeDef = {
   };
   pos: Pos;
 };
+type MotionDef = {
+  kind: "MotionDef";
+  name: string;
+  body: {
+    [k: string]: ThemeValue;
+  };
+  pos: Pos;
+};
 type TypeDef = {
   kind: "TypeDef";
   name: string;
@@ -168,6 +185,7 @@ type EventPattern = {
 } | {
   kind: "TimerEvent";
   intervalMs: number;
+  name?: string;
   pos: Pos;
 } | {
   kind: "LifecycleEvent";
@@ -190,6 +208,10 @@ type Statement = {
   effect: string;
   args: Expr[];
   pos: Pos;
+} | {
+  kind: "StopTimer";
+  name: string;
+  pos: Pos;
 } | {
   kind: "ForStmt";
   bind: string;
@@ -415,9 +437,30 @@ type TileProp = {
   value: Expr;
 };
 //#endregion
+//#region src/capabilities.d.ts
+/** Capabilities that may appear in `app.caps` without any manifest. */
+declare const STANDARD_CAPABILITIES: ReadonlySet<string>;
+type CapabilityManifest = {
+  capabilities: string[];
+};
+type ManifestResult = {
+  ok: true;
+  manifest: CapabilityManifest;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Validate a parsed `kumiki.caps.json` value. Accepts either bare strings or
+ * `{ name, description? }` objects in the `capabilities` array. Pure — the
+ * caller does the file read + JSON parse and reports the location.
+ */
+declare function parseCapabilityManifest(raw: unknown): ManifestResult;
+//#endregion
 //#region src/codegen.d.ts
 type CodegenOptions = {
-  runtimeSpecifier: string;
+  runtimeSpecifier: string; /** Emit the in-language `test` definitions (`__kumikiTests`). Off for production builds. */
+  includeTests?: boolean;
 };
 declare function codegen(program: Program, opts: CodegenOptions): string;
 declare const RUNTIME_HELPERS = "\nfunction _setPath(obj, path, value) {\n  if (path.length === 0) return value;\n  const [head, ...rest] = path;\n  const cur = obj ?? {};\n  return { ...cur, [head]: _setPath(cur[head], rest, value) };\n}\nfunction _children(...xs) {\n  const out = [];\n  for (const x of xs) {\n    if (x === null || x === undefined) continue;\n    if (Array.isArray(x)) {\n      for (const y of x) if (y !== null && y !== undefined) out.push(y);\n    } else {\n      out.push(x);\n    }\n  }\n  return out;\n}\nfunction _attachProps(node, props) {\n  if (!node || !props) return node;\n  return { ...node, props: { ...(node.props || {}), ...props } };\n}\n";
@@ -429,9 +472,15 @@ type KumikiError = {
   message: string;
   pos: Pos;
 };
-/** Returns errors with a11y warnings filtered out (unless strict). */
+/**
+ * Returns errors with a11y warnings filtered out (unless strict).
+ * `capabilities` lists project-registered capabilities (from a
+ * `kumiki.caps.json` manifest) that are accepted in `app.caps` in addition to
+ * the standard set.
+ */
 declare function check(program: Program, opts?: {
   strictA11y?: boolean;
+  capabilities?: string[];
 }): KumikiError[];
 //#endregion
 //#region src/compile.d.ts
@@ -453,7 +502,8 @@ type ExtendedCodegenOptions = CodegenOptions & {
    * Node-only imports, so it can run unchanged in the browser. Node callers can
    * use `nodeRuntimeBundleReader` from `@kumikijs/compiler/node`.
    */
-  readRuntimeBundle?: () => string;
+  readRuntimeBundle?: () => string; /** Project-registered capabilities (from `kumiki.caps.json`) accepted in `app.caps`. */
+  capabilities?: string[];
 };
 /** Inline a runtime bundle into generated module code, stripping the bridging import/export lines. */
 declare function inlineRuntime(generatedJs: string, runtimeBundleJs: string): string;
@@ -469,4 +519,4 @@ declare class ParseError extends Error {
 }
 declare function parse(tokens: Token[]): Program;
 //#endregion
-export { type AppDef, type BinOp, type CodegenOptions, type CompileFail, type CompileOk, type CompileResult, type Def, type EffectDef, type EventPattern, type Expr, type ExtendedCodegenOptions, type FnDef, type KumikiError, type Lvalue, type MatchArm, ParseError, type Pattern, type PolicyExpr, type Pos, type Program, RUNTIME_HELPERS, type ReducerDef, type Refinement, type RetryExpr, type SlotDef, type Statement, type ThemeDef, type ThemeValue, type TileArg, type TileDef, type TileExpr, type TileMatchArm, type TileProp, type Token, type TypeDef, type TypeExpr, type UiEventKind, check, codegen, compile, inlineRuntime, lex, parse };
+export { type AppDef, type BinOp, type CapabilityManifest, type CodegenOptions, type CompileFail, type CompileOk, type CompileResult, type Def, type EffectDef, type EventPattern, type Expr, type ExtendedCodegenOptions, type FnDef, type KumikiError, type Lvalue, type ManifestResult, type MatchArm, type MotionDef, ParseError, type Pattern, type PolicyExpr, type Pos, type Program, RUNTIME_HELPERS, type ReducerDef, type Refinement, type RetryExpr, STANDARD_CAPABILITIES, type SlotDef, type Statement, type TestDef, type ThemeDef, type ThemeValue, type TileArg, type TileDef, type TileExpr, type TileMatchArm, type TileProp, type Token, type TypeDef, type TypeExpr, type UiEventKind, check, codegen, compile, inlineRuntime, lex, parse, parseCapabilityManifest };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { n as parseCapabilityManifest, t as STANDARD_CAPABILITIES } from "./capabilities-Bdub5oAe.js";
 //#region src/codegen.ts
 function codegen(program, opts) {
 	const types = new Map(program.defs.filter((d) => d.kind === "TypeDef").map((d) => [d.name, d]));
@@ -8,6 +9,8 @@ function codegen(program, opts) {
 	const tiles = program.defs.filter((d) => d.kind === "TileDef");
 	const apps = program.defs.filter((d) => d.kind === "AppDef");
 	const themes = program.defs.filter((d) => d.kind === "ThemeDef");
+	const motions = program.defs.filter((d) => d.kind === "MotionDef");
+	const tests = program.defs.filter((d) => d.kind === "TestDef");
 	const app = apps[0];
 	if (!app) throw new Error("No app definition found");
 	const ctx = {
@@ -59,6 +62,10 @@ function codegen(program, opts) {
 	lines.push("};");
 	const themeRef = app.theme ? JSON.stringify(app.theme) : "null";
 	lines.push("");
+	lines.push("const _motions = {");
+	for (const m of motions) lines.push(`  ${JSON.stringify(m.name)}: ${JSON.stringify(m.body)},`);
+	lines.push("};");
+	lines.push("");
 	lines.push("const App = {");
 	lines.push("  slots: _slots,");
 	lines.push(`  caps: ${JSON.stringify(app.caps)},`);
@@ -69,12 +76,110 @@ function codegen(program, opts) {
 	lines.push("  live: _live,");
 	lines.push("  themes: _themes,");
 	lines.push(`  themeName: ${themeRef},`);
+	lines.push("  motions: _motions,");
 	lines.push("};");
 	lines.push("");
 	lines.push("globalThis.__kumikiApp = App;");
+	if (opts.includeTests && tests.length > 0) {
+		lines.push("");
+		lines.push("const _tilesById = {");
+		for (const tile of tiles) lines.push(`  ${JSON.stringify(tile.name)}: (${jsName("$1")}) => ${genTile(tile, ctx)},`);
+		lines.push("};");
+		lines.push("void _tilesById;");
+		lines.push("const __kumikiTests = [");
+		for (const t of tests) lines.push(genTest(t, ctx));
+		lines.push("];");
+		lines.push("globalThis.__kumikiTests = __kumikiTests;");
+	}
+	lines.push("");
 	lines.push(`mount(App, document.getElementById("root"));`);
 	return lines.join("\n");
 }
+function recordField(e, name) {
+	if (e.kind !== "RecordLit") return void 0;
+	return e.fields.find((f) => f.name === name)?.value;
+}
+function genTest(t, gen) {
+	const ctx = makeEvalCtx(gen, /* @__PURE__ */ new Set());
+	const nameJs = JSON.stringify(t.name);
+	if (t.testKind === "reducer-test") {
+		const slots = recordField(t.given, "slots");
+		const event = recordField(t.given, "event");
+		const slotsJs = slots ? jsOfExpr(slots, ctx) : "({})";
+		const elJs = eventPayloadJs(event, ctx);
+		const panic = recordField(t.expect, "panic");
+		let expectJs;
+		if (panic) expectJs = `{ kind: "panic", message: ${jsOfExpr(panic, ctx)} }`;
+		else {
+			const xs = recordField(t.expect, "slots");
+			const xe = recordField(t.expect, "effects");
+			expectJs = `{ kind: "state", slots: ${xs ? jsOfExpr(xs, ctx) : "({})"}, effects: ${xe ? effectListJs(xe, ctx) : "[]"} }`;
+		}
+		return `  {
+    name: ${nameJs},
+    kind: "reducer-test",
+    run: () => {
+      _s.resetLive(_live, _slots, ${slotsJs});
+      const _el = ${elJs};
+      const _r = _reducers.find((r) => r.name === ${JSON.stringify(t.target)});
+      if (!_r) throw new Error("reducer ${t.target} not found");
+      let _res = null, _panic = null;
+      try { _res = _r.apply(_live, { $el: _el, $event: _el }); }
+      catch (e) { _panic = (e && e.message) ? e.message : String(e); }
+      return _s.runReducerTest({ name: ${nameJs}, givenSlots: { ..._live }, result: _res, panic: _panic, expect: ${expectJs} });
+    },
+  },`;
+	}
+	const slots = recordField(t.given, "slots");
+	const slotsJs = slots ? jsOfExpr(slots, ctx) : "({})";
+	const inField = recordField(t.given, "in");
+	const inJs = inField ? jsOfExpr(inField, ctx) : "undefined";
+	const expectedJs = tileExprJs(t.expect, gen, ctx);
+	return `  {
+    name: ${nameJs},
+    kind: "tile-test",
+    run: () => {
+      _s.resetLive(_live, _slots, ${slotsJs});
+      const _actual = _tilesById[${JSON.stringify(t.target)}](${inJs});
+      const _expected = ${expectedJs};
+      return _s.runTileTest({ name: ${nameJs}, actual: _actual, expected: _expected });
+    },
+  },`;
+}
+/**
+* Compile a `[eff(a), ...]` expect.effects list into `[{effect, args, argsSpecified}]`.
+* A bare name (`persist`) matches by name only (`argsSpecified: false`); a call
+* (`persist(x)`, even `persist()`) pins the exact arguments (`argsSpecified: true`).
+*/
+function effectListJs(e, ctx) {
+	if (e.kind !== "ListLit") return "[]";
+	return `[${e.items.map((it) => {
+		if (it.kind === "Call") {
+			const args = it.args.map((a) => jsOfExpr(a, ctx)).join(", ");
+			return `{ effect: ${JSON.stringify(it.callee)}, args: [${args}], argsSpecified: true }`;
+		}
+		if (it.kind === "Ref") return `{ effect: ${JSON.stringify(it.name)}, args: [], argsSpecified: false }`;
+		return `{ effect: "?", args: [], argsSpecified: false }`;
+	}).join(", ")}]`;
+}
+/**
+* The reducer payload (`$el` / `$event`) for a reducer-test's `given.event`.
+* Uses `el` when present (spec §8.5), otherwise the event's other fields
+* (everything except `type` / `target`) so flat `{type, target, value}` forms
+* still reach the reducer.
+*/
+function eventPayloadJs(event, ctx) {
+	if (event?.kind !== "RecordLit") return "({})";
+	const el = event.fields.find((f) => f.name === "el");
+	if (el) return jsOfExpr(el.value, ctx);
+	const rest = event.fields.filter((f) => f.name !== "type" && f.name !== "target");
+	if (rest.length === 0) return "({})";
+	return jsOfExpr({
+		kind: "RecordLit",
+		fields: rest,
+		pos: event.pos
+	}, ctx);
+}
 function makeEvalCtx(gen, locals, reducerScope = false) {
 	return {
 		gen,
@@ -145,11 +250,14 @@ function genReducer(r, gen) {
 		eventJs = `{ kind: "ui", ev: ${JSON.stringify(r.on.ev)} }`;
 		selectorJs = `{ tile: ${JSON.stringify(r.on.selector.tile)}${r.on.selector.id ? `, id: ${JSON.stringify(r.on.selector.id)}` : ""} }`;
 	} else if (r.on.kind === "EffectEvent") eventJs = `{ kind: "effect", effect: ${JSON.stringify(r.on.effect)}, outcome: ${JSON.stringify(r.on.outcome)} }`;
-	else if (r.on.kind === "TimerEvent") eventJs = `{ kind: "timer", intervalMs: ${r.on.intervalMs} }`;
-	else eventJs = `{ kind: "lifecycle", name: ${JSON.stringify(r.on.name)} }`;
+	else if (r.on.kind === "TimerEvent") {
+		const nameJs = r.on.name !== void 0 ? `, name: ${JSON.stringify(r.on.name)}` : "";
+		eventJs = `{ kind: "timer", intervalMs: ${r.on.intervalMs}${nameJs} }`;
+	} else eventJs = `{ kind: "lifecycle", name: ${JSON.stringify(r.on.name)} }`;
 	const stmtLines = [];
 	stmtLines.push(`const _next = {};`);
 	stmtLines.push(`const _emits = [];`);
+	stmtLines.push(`const _stops = [];`);
 	if (r.on.kind === "EffectEvent") for (let i = 0; i < r.on.binds.length; i++) {
 		const name = r.on.binds[i];
 		if (name === "_") continue;
@@ -159,7 +267,7 @@ function genReducer(r, gen) {
 	stmtLines.push(`const ${jsName("$event")} = _payload.$event || _payload || {};`);
 	stmtLines.push(`const ${jsName("$route")} = _payload.$route || {};`);
 	for (const st of r.do) stmtLines.push(genStatement(st, ctx));
-	stmtLines.push(`return { slots: _next, emits: _emits };`);
+	stmtLines.push(`return { slots: _next, emits: _emits, stopTimers: _stops };`);
 	return `  {
     name: ${JSON.stringify(r.name)},
     selector: ${selectorJs},
@@ -206,6 +314,7 @@ function genStatement(s, ctx) {
 		const args = s.args.map((a) => jsOfExpr(a, ctx)).join(", ");
 		return `_emits.push({ effect: ${JSON.stringify(s.effect)}, args: [${args}] });`;
 	}
+	if (s.kind === "StopTimer") return `_stops.push(${JSON.stringify(s.name)});`;
 	return genSlotAssign(s.lvalue, s.rhs, ctx);
 }
 function genSlotAssign(lv, rhs, ctx) {
@@ -283,6 +392,18 @@ function jsOfExpr(e, ctx) {
 			if (e.field === "unique") return `[...new Set((${baseJs}) ?? [])]`;
 			if (e.field === "reverse") return `[...((${baseJs}) ?? [])].reverse()`;
 			if (e.field === "sort") return `[...((${baseJs}) ?? [])].sort()`;
+			if (e.field === "head") return `_s.listHead(${baseJs})`;
+			if (e.field === "tail") return `_s.listTail(${baseJs})`;
+			if (e.field === "last") return `_s.listLast(${baseJs})`;
+			if (e.field === "to-list") return `_s.toList(${baseJs})`;
+			if (e.field === "get-err") return `_s.getErr(${baseJs})`;
+			if (e.field === "to-option") return `_s.toOption(${baseJs})`;
+			if (e.field === "parse-int") return `_s.parseIntOpt(${baseJs})`;
+			if (e.field === "parse-float") return `_s.parseFloatOpt(${baseJs})`;
+			if (e.field === "abs") return `Math.abs(${baseJs})`;
+			if (e.field === "neg") return `(-(${baseJs}))`;
+			if (e.field === "to-float") return `(${baseJs})`;
+			if (e.field === "to-int") return `Math.trunc(${baseJs})`;
 			return `(${baseJs})[${JSON.stringify(e.field)}]`;
 		}
 		case "Index": return `(${jsOfExpr(e.base, ctx)})[${jsOfExpr(e.index, ctx)}]`;
@@ -385,7 +506,19 @@ const KNOWN_METHODS = new Set([
 	"replace",
 	"min",
 	"max",
-	"clamp"
+	"clamp",
+	"head",
+	"tail",
+	"last",
+	"to-list",
+	"get-err",
+	"to-option",
+	"parse-int",
+	"parse-float",
+	"abs",
+	"neg",
+	"to-float",
+	"to-int"
 ]);
 function methodCallJs(recv, method, args, ctx) {
 	const inner = makeEvalCtx(ctx.gen, ctx.localBinds);
@@ -449,6 +582,18 @@ function methodCallJs(recv, method, args, ctx) {
 		case "min": return `Math.min((${recvJs}), (${argRaw(args[0])}))`;
 		case "max": return `Math.max((${recvJs}), (${argRaw(args[0])}))`;
 		case "clamp": return `Math.min(Math.max((${recvJs}), (${argRaw(args[0])})), (${argRaw(args[1])}))`;
+		case "head": return `_s.listHead(${recvJs})`;
+		case "tail": return `_s.listTail(${recvJs})`;
+		case "last": return `_s.listLast(${recvJs})`;
+		case "to-list": return `_s.toList(${recvJs})`;
+		case "get-err": return `_s.getErr(${recvJs})`;
+		case "to-option": return `_s.toOption(${recvJs})`;
+		case "parse-int": return `_s.parseIntOpt(${recvJs})`;
+		case "parse-float": return `_s.parseFloatOpt(${recvJs})`;
+		case "abs": return `Math.abs(${recvJs})`;
+		case "neg": return `(-(${recvJs}))`;
+		case "to-float": return `(${recvJs})`;
+		case "to-int": return `Math.trunc(${recvJs})`;
 		default: return `(${recvJs}).${jsName(method)}(${args.map(argRaw).join(", ")})`;
 	}
 }
@@ -529,6 +674,7 @@ const BUILTIN_TILES$2 = new Set([
 	"panel",
 	"grid",
 	"stack",
+	"overlay",
 	"region",
 	"scroll",
 	"divider",
@@ -621,6 +767,7 @@ function tileCallJs(t, gen, ctx, enclosingTile) {
 		case "box":
 		case "grid":
 		case "stack":
+		case "overlay":
 		case "region":
 		case "scroll":
 		case "divider":
@@ -873,6 +1020,7 @@ const KEYWORDS = new Set([
 	"tile",
 	"fn",
 	"app",
+	"test",
 	"nominal",
 	"where",
 	"when",
@@ -1172,6 +1320,7 @@ const BUILTIN_TILES$1 = new Set([
 	"row",
 	"column",
 	"stack",
+	"overlay",
 	"grid",
 	"box",
 	"card",
@@ -1272,6 +1421,10 @@ var Parser = class {
 				defs.push(this.parseThemeDef());
 				continue;
 			}
+			if (this.matchT("ident", "motion")) {
+				defs.push(this.parseMotionDef());
+				continue;
+			}
 			defs.push(this.parseDef());
 		}
 		return {
@@ -1290,6 +1443,17 @@ var Parser = class {
 			pos: start.pos
 		};
 	}
+	parseMotionDef() {
+		const start = this.eat("ident", "motion");
+		const name = this.eat("ident").value;
+		this.eat("op", "=");
+		return {
+			kind: "MotionDef",
+			name,
+			body: this.parseThemeRecord(),
+			pos: start.pos
+		};
+	}
 	parseThemeRecord() {
 		this.eat("op", "{");
 		const out = {};
@@ -1331,6 +1495,7 @@ var Parser = class {
 			case "fn": return this.parseFn();
 			case "effect": return this.parseEffect();
 			case "app": return this.parseApp();
+			case "test": return this.parseTest();
 			default: throw new ParseError(`Unsupported definition keyword "${t.value}"`, t.pos);
 		}
 	}
@@ -1582,10 +1747,23 @@ var Parser = class {
 			this.next();
 			this.eat("op", "(");
 			const intervalMs = this.parseDuration();
+			let name;
+			if (this.matchOp(",")) {
+				this.next();
+				const kw = this.eat("ident");
+				if (kw.value !== "name") throw new ParseError(`Expected "name=" in timer(...)`, kw.pos);
+				this.eat("op", "=");
+				name = this.eat("ident").value;
+			}
 			this.eat("op", ")");
-			return {
+			return name === void 0 ? {
+				kind: "TimerEvent",
+				intervalMs,
+				pos: t.pos
+			} : {
 				kind: "TimerEvent",
 				intervalMs,
+				name,
 				pos: t.pos
 			};
 		}
@@ -1772,6 +1950,18 @@ var Parser = class {
 				pos: start.pos
 			};
 		}
+		const cur = this.peek();
+		if (cur.kind === "ident" && cur.value === "stop-timer") {
+			this.next();
+			this.eat("op", "(");
+			const name = this.eat("ident").value;
+			this.eat("op", ")");
+			return {
+				kind: "StopTimer",
+				name,
+				pos: cur.pos
+			};
+		}
 		const lvalue = this.parseLvalue();
 		this.eat("op", ":=");
 		return {
@@ -2279,25 +2469,30 @@ var Parser = class {
 			};
 		}
 		let isRecord = false;
-		if (this.peek().kind === "ident") {
+		const k0 = this.peek();
+		if (k0.kind === "ident" || k0.kind === "kw") {
 			const peek1 = this.peek(1);
 			if (peek1.kind === "op" && (peek1.value === "=" || peek1.value === ":" || peek1.value === "," || peek1.value === "}")) isRecord = true;
 		}
 		if (isRecord) {
 			const fields = [];
 			while (true) {
-				const nameTok = this.eat("ident");
+				const keyTok = this.peek();
+				if (keyTok.kind !== "ident" && keyTok.kind !== "kw") throw new ParseError("Expected a record field name", keyTok.pos);
+				const fieldName = keyTok.value;
+				const fieldPos = keyTok.pos;
+				this.next();
 				let value;
 				if (this.matchOp("=") || this.matchOp(":")) {
 					this.next();
 					value = this.parseExpr();
 				} else value = {
 					kind: "Ref",
-					name: nameTok.value,
-					pos: nameTok.pos
+					name: fieldName,
+					pos: fieldPos
 				};
 				fields.push({
-					name: nameTok.value,
+					name: fieldName,
 					value
 				});
 				if (!this.matchOp(",")) break;
@@ -2764,6 +2959,31 @@ var Parser = class {
 		if (t.kind === "kw") return true;
 		return false;
 	}
+	parseTest() {
+		const start = this.eat("kw", "test");
+		const name = this.eat("ident").value;
+		this.eat("op", "=");
+		const kindTok = this.eat("ident");
+		if (kindTok.value !== "reducer-test" && kindTok.value !== "tile-test") throw new ParseError(`Unknown test kind "${kindTok.value}" (expected reducer-test or tile-test)`, kindTok.pos);
+		const target = this.eat("ident").value;
+		const givenKw = this.eat("ident");
+		if (givenKw.value !== "given") throw new ParseError(`Expected "given" in test "${name}"`, givenKw.pos);
+		this.eat("op", "=");
+		const given = this.parseExpr();
+		const expectKw = this.eat("ident");
+		if (expectKw.value !== "expect") throw new ParseError(`Expected "expect" in test "${name}"`, expectKw.pos);
+		this.eat("op", "=");
+		const expect = kindTok.value === "tile-test" ? this.parseTileExpr() : this.parseExpr();
+		return {
+			kind: "TestDef",
+			name,
+			testKind: kindTok.value,
+			target,
+			given,
+			expect,
+			pos: start.pos
+		};
+	}
 	parseQualifiedList() {
 		this.eat("op", "[");
 		const out = [];
@@ -2838,6 +3058,7 @@ const BUILTIN_TILES = new Set([
 	"row",
 	"column",
 	"stack",
+	"overlay",
 	"grid",
 	"box",
 	"card",
@@ -2886,13 +3107,18 @@ const A11Y_CODES = new Set([
 	"E0702",
 	"E0703"
 ]);
-/** Returns errors with a11y warnings filtered out (unless strict). */
+/**
+* Returns errors with a11y warnings filtered out (unless strict).
+* `capabilities` lists project-registered capabilities (from a
+* `kumiki.caps.json` manifest) that are accepted in `app.caps` in addition to
+* the standard set.
+*/
 function check(program, opts) {
-	const errors = checkAll(program);
+	const errors = checkAll(program, new Set(opts?.capabilities ?? []));
 	if (opts?.strictA11y) return errors;
 	return errors.filter((e) => !A11Y_CODES.has(e.code));
 }
-function checkAll(program) {
+function checkAll(program, registeredCaps) {
 	const errors = [];
 	const sym = {
 		types: /* @__PURE__ */ new Map(),
@@ -2900,7 +3126,9 @@ function checkAll(program) {
 		reducers: /* @__PURE__ */ new Map(),
 		tiles: /* @__PURE__ */ new Map(),
 		fns: /* @__PURE__ */ new Map(),
-		effects: /* @__PURE__ */ new Map()
+		effects: /* @__PURE__ */ new Map(),
+		timerNames: /* @__PURE__ */ new Set(),
+		motions: /* @__PURE__ */ new Set()
 	};
 	for (const def of program.defs) switch (def.kind) {
 		case "TypeDef":
@@ -2911,6 +3139,13 @@ function checkAll(program) {
 			break;
 		case "ReducerDef":
 			sym.reducers.set(def.name, def);
+			if (def.on.kind === "TimerEvent" && def.on.name !== void 0) if (sym.timerNames.has(def.on.name)) errors.push({
+				code: "E0002",
+				kind: "duplicate-timer-name",
+				message: `Timer name "${def.on.name}" is declared more than once`,
+				pos: def.on.pos
+			});
+			else sym.timerNames.add(def.on.name);
 			break;
 		case "TileDef":
 			sym.tiles.set(def.name, def);
@@ -2921,6 +3156,9 @@ function checkAll(program) {
 		case "EffectDef":
 			sym.effects.set(def.name, def);
 			break;
+		case "MotionDef":
+			sym.motions.add(def.name);
+			break;
 		case "AppDef":
 			sym.app = def;
 			break;
@@ -2931,10 +3169,137 @@ function checkAll(program) {
 		if (def.kind === "ReducerDef") checkReducer(def, sym, errors);
 		if (def.kind === "FnDef") checkFn(def, sym, errors);
 		if (def.kind === "EffectDef") checkEffect(def, sym, errors);
-		if (def.kind === "AppDef") checkApp(def, sym, errors);
+		if (def.kind === "AppDef") checkApp(def, sym, errors, registeredCaps);
+		if (def.kind === "MotionDef") checkMotion(def, errors);
+		if (def.kind === "TestDef") checkTest(def, sym, errors);
 	}
 	return errors;
 }
+const MOTION_KEYFRAME_PROPS = new Set([
+	"opacity",
+	"translate-x",
+	"translate-y",
+	"scale",
+	"rotate"
+]);
+const MOTION_EASINGS = new Set([
+	"linear",
+	"ease",
+	"ease-in",
+	"ease-out",
+	"ease-in-out"
+]);
+const MOTION_DURATION_TOKENS = new Set([
+	"fast",
+	"normal",
+	"slow"
+]);
+const MOTION_DIRECTIONS = new Set([
+	"normal",
+	"reverse",
+	"alternate",
+	"alternate-reverse"
+]);
+const MOTION_TIMING_KEYS = new Set([
+	"duration",
+	"easing",
+	"iteration",
+	"direction"
+]);
+/** `duration` (ms) and `iteration` are spec'd as positive integers (no 0 / negative / float). */
+const isPositiveInt = (v) => typeof v === "number" && Number.isInteger(v) && v > 0;
+/**
+* Validate a `motion` definition against the closed grammar (ADR-001). Purity
+* (no slots/effects) is already guaranteed by the parser — the body is a literal
+* record — so this only enforces the closed property + timing vocabularies.
+*/
+function checkMotion(def, errors) {
+	const body = def.body;
+	const keyframes = body.keyframes;
+	if (typeof keyframes !== "object" || Array.isArray(keyframes)) {
+		errors.push({
+			code: "E0403",
+			kind: "motion-malformed",
+			message: `motion "${def.name}" must declare a "keyframes" record`,
+			pos: def.pos
+		});
+		return;
+	}
+	const stops = keyframes;
+	for (const required of ["from", "to"]) {
+		const stop = stops[required];
+		if (typeof stop !== "object" || Array.isArray(stop)) {
+			errors.push({
+				code: "E0403",
+				kind: "motion-malformed",
+				message: `motion "${def.name}" keyframes must include a "${required}" record`,
+				pos: def.pos
+			});
+			return;
+		}
+	}
+	for (const stopName of Object.keys(stops)) {
+		if (stopName !== "from" && stopName !== "to") {
+			errors.push({
+				code: "E0403",
+				kind: "motion-malformed",
+				message: `motion "${def.name}" keyframes support only "from" / "to" (got "${stopName}")`,
+				pos: def.pos
+			});
+			continue;
+		}
+		const stop = stops[stopName];
+		for (const [prop, val] of Object.entries(stop)) if (!MOTION_KEYFRAME_PROPS.has(prop)) errors.push({
+			code: "E0401",
+			kind: "motion-unknown-property",
+			message: `motion "${def.name}": unknown keyframe property "${prop}" (allowed: ${[...MOTION_KEYFRAME_PROPS].join(", ")})`,
+			pos: def.pos
+		});
+		else if (typeof val !== "number") errors.push({
+			code: "E0401",
+			kind: "motion-unknown-property",
+			message: `motion "${def.name}": keyframe property "${prop}" must be a number`,
+			pos: def.pos
+		});
+	}
+	for (const key of Object.keys(body)) {
+		if (key === "keyframes") continue;
+		if (!MOTION_TIMING_KEYS.has(key)) errors.push({
+			code: "E0402",
+			kind: "motion-invalid-timing",
+			message: `motion "${def.name}": unknown field "${key}" (allowed: keyframes, ${[...MOTION_TIMING_KEYS].join(", ")})`,
+			pos: def.pos
+		});
+	}
+	const dur = body.duration;
+	if (dur !== void 0 && !(isPositiveInt(dur) || MOTION_DURATION_TOKENS.has(String(dur)))) errors.push({
+		code: "E0402",
+		kind: "motion-invalid-timing",
+		message: `motion "${def.name}": duration must be a positive Int (ms) or one of fast/normal/slow`,
+		pos: def.pos
+	});
+	const eas = body.easing;
+	if (eas !== void 0 && !MOTION_EASINGS.has(String(eas))) errors.push({
+		code: "E0402",
+		kind: "motion-invalid-timing",
+		message: `motion "${def.name}": easing must be one of ${[...MOTION_EASINGS].join(", ")}`,
+		pos: def.pos
+	});
+	const iter = body.iteration;
+	if (iter !== void 0 && !(isPositiveInt(iter) || iter === "infinite")) errors.push({
+		code: "E0402",
+		kind: "motion-invalid-timing",
+		message: `motion "${def.name}": iteration must be a positive Int or "infinite"`,
+		pos: def.pos
+	});
+	const dir = body.direction;
+	if (dir !== void 0 && !MOTION_DIRECTIONS.has(String(dir))) errors.push({
+		code: "E0402",
+		kind: "motion-invalid-timing",
+		message: `motion "${def.name}": direction must be one of ${[...MOTION_DIRECTIONS].join(", ")}`,
+		pos: def.pos
+	});
+}
 function checkSlot(slot, sym, errors) {
 	resolveType(slot.type, sym, errors);
 	checkExpr(slot.init, sym, errors, {
@@ -3072,6 +3437,13 @@ function checkTileCall(t, sym, errors, ctx) {
 			message: `Reference to undefined reducer "${ref.name}"`,
 			pos: ref.pos
 		});
+	} else if (prop.name === "motion" && prop.value.kind === "Str") {
+		if (!sym.motions.has(prop.value.value)) errors.push({
+			code: "E0107",
+			kind: "undef-motion",
+			message: `Reference to undefined motion "${prop.value.value}"`,
+			pos: prop.value.pos
+		});
 	} else checkExpr(prop.value, sym, errors, ctx);
 }
 function checkReducer(r, sym, errors) {
@@ -3158,6 +3530,15 @@ function checkStmt(s, sym, errors, ctx, writtenRoots) {
 		for (const a of s.args) checkExpr(a, sym, errors, ctx);
 		return;
 	}
+	if (s.kind === "StopTimer") {
+		if (!sym.timerNames.has(s.name)) errors.push({
+			code: "E0106",
+			kind: "undef-timer",
+			message: `stop-timer refers to undefined timer name "${s.name}"`,
+			pos: s.pos
+		});
+		return;
+	}
 	const root = lvalueRoot(s.lvalue);
 	if (!sym.slots.has(root)) errors.push({
 		code: "E0103",
@@ -3325,7 +3706,34 @@ function checkEffect(eff, sym, errors) {
 		localBinds: new Set(["$1"])
 	});
 }
-function checkApp(app, sym, errors) {
+function checkTest(t, sym, errors) {
+	if (t.testKind === "reducer-test") {
+		if (!sym.reducers.has(t.target)) errors.push({
+			code: "E0102",
+			kind: "undef-reducer",
+			message: `Reference to undefined reducer "${t.target}"`,
+			pos: t.pos
+		});
+		return;
+	}
+	if (!BUILTIN_TILES.has(t.target) && !sym.tiles.has(t.target)) errors.push({
+		code: "E0105",
+		kind: "undef-tile",
+		message: `Reference to undefined tile "${t.target}"`,
+		pos: t.pos
+	});
+	checkTileExpr(t.expect, sym, errors, {
+		kind: "tile",
+		localBinds: /* @__PURE__ */ new Set()
+	});
+}
+function checkApp(app, sym, errors, registeredCaps) {
+	for (const cap of app.caps) if (!STANDARD_CAPABILITIES.has(cap) && !registeredCaps.has(cap)) errors.push({
+		code: "E0302",
+		kind: "unknown-capability",
+		message: `Unknown capability "${cap}" in app.caps — use a standard capability or register it in kumiki.caps.json`,
+		pos: app.pos
+	});
 	let saw404 = false;
 	for (const r of app.routes) {
 		if (r.tile.startsWith(">>")) continue;
@@ -3380,7 +3788,7 @@ function inlineRuntime(generatedJs, runtimeBundleJs) {
 }
 function compile(source, opts) {
 	const program = parse(lex(source));
-	const errors = check(program);
+	const errors = check(program, { capabilities: opts.capabilities ?? [] });
 	if (errors.length > 0) return {
 		kind: "fail",
 		errors
@@ -3397,4 +3805,4 @@ function compile(source, opts) {
 	};
 }
 //#endregion
-export { ParseError, RUNTIME_HELPERS, check, codegen, compile, inlineRuntime, lex, parse };
+export { ParseError, RUNTIME_HELPERS, STANDARD_CAPABILITIES, check, codegen, compile, inlineRuntime, lex, parse, parseCapabilityManifest };

package/dist/node.d.ts

@@ -4,5 +4,15 @@
  * `compile(source, { bundle: true, readRuntimeBundle: nodeRuntimeBundleReader })`.
  */
 declare function nodeRuntimeBundleReader(): string;
+/** Thrown when a `kumiki.caps.json` exists but is malformed. */
+declare class CapabilityManifestError extends Error {}
+/**
+ * Resolve project-registered capabilities from a `kumiki.caps.json` in the same
+ * directory as the given `.kumiki` file. Returns `[]` when no manifest exists;
+ * throws `CapabilityManifestError` (with the path) when one exists but is
+ * invalid. Pass the result as `compile(src, { capabilities })` /
+ * `check(program, { capabilities })`.
+ */
+declare function resolveCapabilities(kumikiFilePath: string): string[];
 //#endregion
-export { nodeRuntimeBundleReader };
+export { CapabilityManifestError, nodeRuntimeBundleReader, resolveCapabilities };

package/dist/node.js

@@ -1,5 +1,7 @@
+import { n as parseCapabilityManifest } from "./capabilities-Bdub5oAe.js";
 import { createRequire } from "node:module";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 //#region src/node.ts
 /**
 * Reads the prebuilt @kumikijs/runtime bundle from disk. Pass as
@@ -8,5 +10,27 @@ import { readFileSync } from "node:fs";
 function nodeRuntimeBundleReader() {
 	return readFileSync(createRequire(import.meta.url).resolve("@kumikijs/runtime/bundle"), "utf8");
 }
+/** Thrown when a `kumiki.caps.json` exists but is malformed. */
+var CapabilityManifestError = class extends Error {};
+/**
+* Resolve project-registered capabilities from a `kumiki.caps.json` in the same
+* directory as the given `.kumiki` file. Returns `[]` when no manifest exists;
+* throws `CapabilityManifestError` (with the path) when one exists but is
+* invalid. Pass the result as `compile(src, { capabilities })` /
+* `check(program, { capabilities })`.
+*/
+function resolveCapabilities(kumikiFilePath) {
+	const manifestPath = join(dirname(kumikiFilePath), "kumiki.caps.json");
+	if (!existsSync(manifestPath)) return [];
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+	} catch (e) {
+		throw new CapabilityManifestError(`${manifestPath}: invalid JSON — ${e.message}`);
+	}
+	const result = parseCapabilityManifest(raw);
+	if (!result.ok) throw new CapabilityManifestError(`${manifestPath}: ${result.error}`);
+	return result.manifest.capabilities;
+}
 //#endregion
-export { nodeRuntimeBundleReader };
+export { CapabilityManifestError, nodeRuntimeBundleReader, resolveCapabilities };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kumikijs/compiler",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Kumiki compiler — lexer, parser, typechecker, and code generator.",
   "license": "Apache-2.0",
@@ -26,11 +26,11 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "import": "./dist/index.js"
     },
     "./node": {
       "types": "./dist/node.d.ts",
-      "default": "./src/node.ts"
+      "import": "./dist/node.js"
     }
   },
   "files": [
@@ -38,30 +38,20 @@
   ],
   "publishConfig": {
     "access": "public",
-    "provenance": true,
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.ts",
-        "import": "./dist/index.js"
-      },
-      "./node": {
-        "types": "./dist/node.d.ts",
-        "import": "./dist/node.js"
-      }
-    }
+    "provenance": true
+  },
+  "dependencies": {
+    "@kumikijs/runtime": "0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "lint": "biome check src test"
-  },
-  "dependencies": {
-    "@kumikijs/runtime": "workspace:*"
-  },
-  "devDependencies": {
-    "@types/node": "catalog:",
-    "typescript": "catalog:",
-    "vitest": "catalog:"
   }
-}
+}