@clicksmith/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClickSmith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @clicksmith/core
+
+Platform-neutral shared contracts for ClickSmith. This package is the single
+source of truth for the data that flows between the browser extension, the
+daemon, the MCP server, and agent adapters.
+
+> It has **no Node or browser runtime assumptions** beyond [`zod`](https://zod.dev),
+> so it can be imported from a content script, a Fastify route, or a CLI alike.
+
+## What's inside
+
+| Module | Exports |
+| --- | --- |
+| `schemas` | Zod schemas: `LocatorSchema`, `CapturedElementSchema`, `ExecutionOptionsSchema`, `CaptureBundleSchema` (v5), `SessionSchema`, … |
+| `types` | Inferred TS types for everything above (`Locator`, `CaptureBundle`, `Session`, …). |
+| `ids` | `newSessionId`, `newRunId`, `nextElementId`, `parseElementRef`. |
+| `locator` | `LOCATOR_PRIORITY`, `rankLocators`, `pickBestLocator`, `describeLocator`. |
+| `session` | `createSession`, `appendElement`, `removeElement`, `finalizeSession`, `isExpired`, `touchSession`. |
+| `bundle` | `validateBundle`, `parseBundle`, `serializeBundle`, `deserializeBundle`. |
+| `defaults` | `DEFAULT_EXECUTION_OPTIONS`, `requiresConfirmation`, `DEFAULT_SESSION_TTL_MS`, port defaults. |
+| `protocol` | HTTP DTOs (`CaptureRequest`, `SubmitRequest`, …) and the `ServerEvent` WebSocket union. |
+
+## The capture bundle (v5)
+
+```ts
+import { CaptureBundleSchema, type CaptureBundle } from '@clicksmith/core';
+
+const bundle: CaptureBundle = CaptureBundleSchema.parse(payload);
+```
+
+```jsonc
+{
+  "v": 5,
+  "sessionId": "cs_…",
+  "submittedAt": "2026-06-07T10:05:00.000Z",
+  "prompt": "make #1 match #2's style",
+  "app": { "url": "…", "route": "/pricing", "page": "Pricing" },
+  "elements": [ /* CapturedElement[] */ ],
+  "execution": { "mode": "plan", "isolation": "worktree", "autoApply": false },
+  "enrichment": { /* optional code-review-graph context */ }
+}
+```
+
+## Locator ranking
+
+Locators are a discriminated union ranked **exactly** `source → attr → behavioral → dom`:
+
+```ts
+import { pickBestLocator } from '@clicksmith/core';
+
+pickBestLocator([domLocator, attrLocator, sourceLocator]); // → sourceLocator
+```
+
+## Safety defaults
+
+`plan + worktree + no auto-apply` is the immutable safe path. `requiresConfirmation()`
+returns `true` for any deviation (edit mode, in-place isolation, or auto-apply), and
+`confirmationReasons()` explains why — drive your confirmation UI from these.
+
+## Scripts
+
+```bash
+pnpm build      # tsup → dist (ESM + d.ts)
+pnpm test       # vitest
+pnpm typecheck  # tsc --noEmit
+```