@ikenga/contract 0.7.0 → 0.9.0

package/README.md

@@ -1,38 +1,83 @@
 # @ikenga/contract
 
-The single source of truth for how the **Ikenga shell**, **pkgs**, and **engines** talk to each other.
+[![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/Royalti-io/ikenga-contract/actions)
+[![Version](https://img.shields.io/badge/version-v0.2.0-blue.svg)](https://github.com/Royalti-io/ikenga-contract/releases)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Discussions](https://img.shields.io/badge/community-discussions-5865F2.svg)](https://github.com/Royalti-io/ikenga-contract/discussions)
 
-This package is intentionally small and stable. Bumping its major version is an event coordinated across the shell + every published pkg.
+> The single source of truth for how the Ikenga shell, pkgs, and engines talk to each
+> other.
+
+## What it is
+
+`@ikenga/contract` is the shared TypeScript package that defines the wire between the
+[Ikenga shell](https://github.com/Royalti-io/ikenga), its packages, and its engine
+adapters: the manifest schema, the RPC envelope, the Engine interface, and the capability
+scope catalogue. It's intentionally small and stable — bumping its major version is an
+event coordinated across the shell and every published pkg.
+
+## Install
+
+```bash
+pnpm add @ikenga/contract
+```
+
+In the workspace, this resolves as `workspace:*`.
 
 ## What's in here
 
 | Module | Exports |
 |--------|---------|
-| `@ikenga/contract/manifest` | `ikenga-pkg.toml` schema (zod) — `ManifestSchema`, `Manifest` type |
+| `@ikenga/contract/manifest` | `ikenga-pkg.toml` schema (Zod) — `ManifestSchema`, `Manifest` type |
 | `@ikenga/contract/rpc` | Shell ↔ pkg postMessage RPC envelope, request/response types |
 | `@ikenga/contract/engine` | `Engine` interface, `Session`, `EngineEvent` types |
 | `@ikenga/contract/scopes` | Capability scope catalogue (`tasks:read`, `engine:invoke`, …) |
-| `@ikenga/contract/artifact` | Ikenga artifact manifest schema (zod) — `ArtifactManifestSchema`, `ArtifactManifest` type, refresh / data-source / fallback sub-schemas |
+| `@ikenga/contract/artifact` | Artifact manifest schema (Zod) — `ArtifactManifestSchema`, `ArtifactManifest` type, refresh / data-source / fallback sub-schemas |
 
 ## Artifact manifest
 
-The artifact manifest is the JSON block embedded in `<script type="application/json" id="ikenga-manifest">…</script>` (single-file artifacts) or in `manifest.json` (folder mode). It's a separate concept from the pkg manifest — pkgs are heavyweight Tauri-side mini-apps; artifacts are portable HTML docs that render anywhere and light up with live data inside the Ikenga shell.
+The artifact manifest is the JSON block embedded in
+`<script type="application/json" id="ikenga-manifest">…</script>` (single-file artifacts) or
+in `manifest.json` (folder mode). It's a separate concept from the pkg manifest — pkgs are
+heavyweight Tauri-side mini-apps; artifacts are portable HTML docs that render anywhere and
+light up with live data inside the shell.
 
 - Source of truth: `src/artifact.ts` (Zod).
 - Generated JSON Schema: `schemas/artifact/v0.json` — regenerate with `pnpm generate:schemas` after schema edits.
-- Published at: `https://royalti-io.github.io/ikenga-contract/schemas/artifact/v0.json` (`$id` is stamped at generation time).
+- Published at: `https://royalti-io.github.io/ikenga-contract/schemas/artifact/v0.json` (`$id` stamped at generation time).
 - Fixtures (the three v0 example artifacts) live in `src/artifact-fixtures/` and are gated by `pnpm test`.
 
 ## Versioning
 
-Strict semver. Pkgs declare `"contract": "^1"` and the kernel checks compatibility at install time.
+Strict semver. Pkgs declare `"contract": "^1"` and the kernel checks compatibility at
+install time.
 
 ## Source of truth
 
-The `Manifest` schema **mirrors** the Rust struct in `royalti-io/ikenga` at `src-tauri/src/pkg/manifest.rs`. The Rust kernel parses pkg `manifest.json` files; this package is a TS-side validator and types-only mirror for tooling (CLI, registry build).
-
-If you need to change the manifest, change the Rust struct first and update this schema in lockstep.
+The `Manifest` schema **mirrors** the Rust struct in
+[`Royalti-io/ikenga`](https://github.com/Royalti-io/ikenga) at
+`src-tauri/src/pkg/manifest.rs`. The Rust kernel parses pkg `manifest.json` files; this
+package is a TS-side validator and types-only mirror for tooling (CLI, registry build). To
+change the manifest, change the Rust struct first and update this schema in lockstep.
 
 ## Status
 
-`v0.2.0` — manifest realigned to the real Rust schema (was a speculative parallel in v0.1.0). RPC method catalogue, engine interface, and capability scopes still in place but unused by the kernel today; treat them as forward-looking.
+`v0.2.0` — manifest realigned to the real Rust schema (was a speculative parallel in
+v0.1.0). RPC method catalogue, engine interface, and capability scopes are still in place
+but unused by the kernel today; treat them as forward-looking.
+
+## Links
+
+- [ikenga.dev](https://ikenga.dev) — site + docs
+- [`ikenga`](https://github.com/Royalti-io/ikenga) — the desktop shell (owns the Rust source of truth)
+- [`ikenga-pkgs`](https://github.com/Royalti-io/ikenga-pkgs) — first-party packages
+
+## License
+
+Apache-2.0 — see [`LICENSE`](LICENSE).
+
+## Contributing & community
+
+Issues and PRs welcome. Start a thread in
+[Discussions](https://github.com/Royalti-io/ikenga-contract/discussions).
+<!-- VERIFY: link CONTRIBUTING.md / CODE_OF_CONDUCT.md once the org .github defaults or per-repo copies exist. -->

package/dist/canvas/Canvas.d.ts

@@ -0,0 +1,7 @@
+import { type ReactElement } from 'react';
+import './canvas.css';
+import type { CanvasHandle, CanvasProps } from './types.js';
+export declare const Canvas: <T>(props: CanvasProps<T> & {
+    ref?: React.Ref<CanvasHandle>;
+}) => ReactElement;
+//# sourceMappingURL=Canvas.d.ts.map

package/dist/canvas/Canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Canvas.d.ts","sourceRoot":"","sources":["../../src/canvas/Canvas.tsx"],"names":[],"mappings":"AAkBA,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AACf,OAAO,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAA2B,MAAM,YAAY,CAAC;AAmIrF,eAAO,MAAM,MAAM,EAA8B,CAAC,CAAC,EACjD,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;CAAE,KACtD,YAAY,CAAC"}

package/dist/canvas/Canvas.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// <Canvas> — the reusable free-form pan/zoom/grid-snap surface extracted from
+// the shell home page. Composes usePanZoom + useDragSnap and renders the
+// stage + items; the consumer supplies item content via `renderItem` and owns
+// `layout` / `editMode` / `selectedId` (all controlled props).
+//
+// Item DOM: Canvas does NOT wrap items in an extra positioned div. It clones
+// the element `renderItem` returns and injects `data-id`, the canvas-space
+// left/top/width geometry, and the `is-selected` class onto it. So the
+// consumer's own card element stays the positioned box — DOM shape matches the
+// pre-extraction home exactly. The cloned element must carry its base class
+// (e.g. `home-widget` / `home-greeting`) and `position: absolute` (the bundled
+// canvas.css supplies the latter for the home classes).
+//
+// CSS: canvas.css is imported as a side effect here, so any bundler following
+// the import graph (Vite in a pkg, the shell's build) inlines it. Its
+// var(--*) tokens resolve against the host document — inside a Vite/iframe pkg
+// the consumer must import @ikenga/tokens at entry (Round 8 / G21).
+import { cloneElement, forwardRef, isValidElement, useImperativeHandle, } from 'react';
+import './canvas.css';
+import { usePanZoom } from './use-pan-zoom.js';
+import { useDragSnap } from './use-drag-snap.js';
+// Hit-test class roots Canvas owns. Anything matching these inside the canvas
+// counts as a draggable item; the bar/palette are excluded from gestures.
+const ITEM_SELECTOR = '.home-widget, .home-greeting, [data-canvas-item]';
+const BAR_SELECTOR = '.ikenga-canvas-bar';
+const PALETTE_SELECTOR = '.home-palette';
+function CanvasInner(props, ref) {
+    const { items, itemId, itemKind, layout, viewport, editMode, selectedId = null, gridSnap = 12, renderItem, onLayoutChange, onViewportChange, onEditModeChange, onSelectionChange, autoFitOnResize = true, className, } = props;
+    const { pan, autoFit, canvasRef, stageRef, spaceDown, beginPan, isPanning } = usePanZoom({
+        layout,
+        editMode,
+        autoFitOnResize,
+        onViewportChange,
+        onEditModeChange,
+        onSelectionChange,
+    });
+    const { beginDrag } = useDragSnap({
+        layout,
+        gridSnap,
+        scale: viewport.scale,
+        onLayoutChange,
+        stageRef,
+    });
+    useImperativeHandle(ref, () => ({ autoFit }), [autoFit]);
+    function onMouseDown(e) {
+        const target = e.target;
+        if (target.closest(BAR_SELECTOR) || target.closest(PALETTE_SELECTOR))
+            return;
+        const middle = e.button === 1;
+        const itemEl = target.closest(ITEM_SELECTOR);
+        if (editMode && itemEl && !middle && !spaceDown.current) {
+            const id = itemEl.getAttribute('data-id');
+            if (!id)
+                return;
+            onSelectionChange?.(id);
+            beginDrag(id, e.clientX, e.clientY);
+            e.preventDefault();
+            return;
+        }
+        if (middle || spaceDown.current || (!editMode && !itemEl)) {
+            beginPan(e.clientX, e.clientY);
+            e.preventDefault();
+        }
+        if (editMode && !itemEl)
+            onSelectionChange?.(null);
+    }
+    function onDoubleClick(e) {
+        const t = e.target;
+        if (t.closest(ITEM_SELECTOR) || t.closest(BAR_SELECTOR) || t.closest(PALETTE_SELECTOR))
+            return;
+        autoFit(true);
+    }
+    const transform = `translate(${pan.x}px, ${pan.y}px) scale(${pan.scale})`;
+    return (_jsxs("div", { ref: canvasRef, className: className ? `ikenga-canvas ${className}` : 'ikenga-canvas', "data-mode-edit": editMode ? 'true' : 'false', onMouseDown: onMouseDown, onDoubleClick: onDoubleClick, children: [_jsx("div", { className: "ikenga-canvas-grain" }), _jsx("div", { ref: stageRef, className: "ikenga-canvas-stage", style: { transform }, children: items.map((item) => {
+                    const id = itemId(item);
+                    const placement = layout[id];
+                    if (!placement)
+                        return null;
+                    const isSelected = selectedId === id;
+                    const state = {
+                        id,
+                        kind: itemKind(item),
+                        placement,
+                        isSelected,
+                        isEditMode: editMode,
+                    };
+                    const node = renderItem(item, state);
+                    if (!isValidElement(node))
+                        return node;
+                    const el = node;
+                    // Inject geometry under the consumer's own style so renderItem can
+                    // still override (e.g. minHeight vs height for the naked greeting).
+                    const injected = {
+                        left: placement.x,
+                        top: placement.y,
+                        width: placement.w,
+                        ...el.props.style,
+                    };
+                    // Append the selection class without clobbering the consumer's.
+                    const baseClass = el.props.className ?? '';
+                    const className = isSelected ? `${baseClass} is-selected`.trim() : baseClass;
+                    return cloneElement(el, {
+                        key: id,
+                        'data-id': id,
+                        style: injected,
+                        className,
+                    });
+                }) }), props.children] }));
+}
+// forwardRef can't preserve the <T> generic through its typing, so we cast the
+// wrapped component back to a generic-aware signature. Callers get full
+// inference on CanvasProps<T>.
+export const Canvas = forwardRef(CanvasInner);
+//# sourceMappingURL=Canvas.js.map

package/dist/canvas/Canvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Canvas.js","sourceRoot":"","sources":["../../src/canvas/Canvas.tsx"],"names":[],"mappings":"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"}