@neonwatty/limner 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@neonwatty/limner",
+  "version": "0.1.0",
+  "description": "Agent-guided visual fidelity workbench for turning images into HTML references and comparing references to real apps.",
+  "type": "module",
+  "bin": {
+    "limn": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "docs",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "check": "npm run lint && npm run typecheck && npm test && npm run build && npm run knip && npm run check:size",
+    "check:size": "node scripts/check-file-size.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "dev": "tsx src/cli.ts",
+    "knip": "knip",
+    "lint": "eslint .",
+    "lint:staged": "lint-staged",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs,ts,tsx}": [
+      "eslint --fix --no-error-on-unmatched-pattern"
+    ],
+    "*": [
+      "node scripts/check-file-size.mjs --staged"
+    ]
+  },
+  "keywords": [
+    "visual-regression",
+    "design",
+    "playwright",
+    "cli",
+    "agent"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "playwright": "^1.57.0",
+    "sharp": "^0.34.5",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.0.0",
+    "eslint": "^10.4.1",
+    "knip": "^6.16.1",
+    "lint-staged": "^17.0.7",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^4.1.0"
+  }
+}

package/skills/limner/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: limner
+description: Use when turning an image into a reference HTML facsimile or comparing approved reference HTML against a real app implementation.
+---
+
+# Limner
+
+Use Limner for structured visual fidelity loops.
+
+## Image To Reference
+
+1. Run `limn init <image> --target <name>` if the target does not exist.
+2. Inspect `source/ideal.png`.
+3. Fill `contract/regions.json`, `contract/tokens.json`, and `contract/acceptance.md`.
+4. Edit `reference/index.html` and `reference/styles.css`.
+5. Run `limn compare image-reference --target <name>`.
+6. Review `captures/image-reference/side-by-side.png`.
+7. Record findings in `reports/image-reference.md`.
+
+Optional structured spec layer:
+
+- Run `limn compare image-reference --target <name> --spec`.
+- Edit `contract/visual-spec-instructions.md` to customize the agent prompt for this target, or pass `--spec-instructions <path>` for a shared policy file.
+- Use `captures/image-reference/spec/agent-prompt.codex.md` for Codex or `captures/image-reference/spec/agent-prompt.claude.md` for Claude.
+- Use the generated `captures/image-reference/spec/agent-response.schema.json` for strict structured output when the agent supports it.
+- The agent should inspect the ideal image and reference screenshot separately. The side-by-side is comparison context, not the image to parse.
+- Have the agent write `captures/image-reference/spec/agent-response.json`.
+- Rerun the same command so Limner can validate the response and emit the spec and diff JSON artifacts.
+
+## Reference To App
+
+1. Confirm the reference HTML is approved.
+2. Ensure every important region has both `referenceSelector` and `appSelector`.
+3. Run `limn compare reference-app --target <name> --url <app-url>`.
+4. Review `captures/reference-app/side-by-side.png` and `dom-metrics.json`.
+5. Use the report to drive one scoped app fix.
+6. Rerun after the fix.
+
+## Image To App Grounding
+
+Use `limn compare image-app --target <name> --url <app-url>` to compare the source image directly to an app screenshot.
+
+Add `--storage-state <path>` for authenticated pages and `--full-page` only when a full-page screenshot is intended. The default is viewport-only.
+
+For generated-image reconstruction work, do not skip Image To Reference. Build the HTML facsimile first, then compare the approved reference to the app.
+
+## Constraints
+
+- Limner does not call an AI vision model itself. The `--spec` workflow requires an external agent.
+- Limner does not make final pass/fail judgments.
+- Limner logs only local JSONL events under `.limner/runs/`.

package/templates/target/AGENT_GUIDE.md

@@ -0,0 +1,24 @@
+# Agent Guide
+
+Use this target folder as a structured workbench for visual fidelity.
+
+## Loop 1: Image To Reference
+
+1. Inspect `source/ideal.png`.
+2. Fill out `contract/regions.json`, `contract/tokens.json`, and `contract/acceptance.md`.
+3. Edit `reference/index.html` and `reference/styles.css` until the reference is a faithful HTML facsimile.
+4. Run `limn compare image-reference --target <target>`.
+5. Review `captures/image-reference/side-by-side.png` and `reports/image-reference.md`.
+6. Record remaining mismatches or intentional deviations.
+
+## Loop 2: Reference To App
+
+1. Treat the reference HTML as the approved design.
+2. Add app selectors to `contract/regions.json`.
+3. Run `limn compare reference-app --target <target> --url <app-url>`.
+4. Review screenshots, DOM metrics, and `reports/reference-app.md`.
+5. Fix the app, rerun the comparison, and keep notes in the report.
+
+## Rule
+
+Limner does not decide visual success automatically. It produces evidence so the agent and human can make sharper decisions.

package/templates/target/contract/acceptance.md

@@ -0,0 +1,23 @@
+# Acceptance Notes
+
+## Required Regions
+
+- `reference-root`: the complete reference surface.
+
+## Intentional Differences
+
+- Record any visual or product-truth deviations here before treating the reference as approved.
+
+## Forbidden Affordances
+
+- Do not add fake navigation, forms, or actions that do not exist in the app implementation.
+
+## Top Failure Modes
+
+1. The reference HTML captures the rough layout but misses the visual hierarchy of the input image.
+2. The app implementation matches colors or copy while missing the actual region proportions.
+3. Disabled or unavailable actions look enabled.
+
+## Negative Checks
+
+- Confirm clipped text, overflow, and disabled affordances are explicitly reviewed.

package/templates/target/contract/regions.json

@@ -0,0 +1,11 @@
+{
+  "regions": [
+    {
+      "id": "reference-root",
+      "label": "Reference Root",
+      "referenceSelector": "[data-limner-region='reference-root']",
+      "appSelector": "body",
+      "checks": ["bounds", "visible", "computed-style", "text"]
+    }
+  ]
+}

package/templates/target/contract/tokens.json

@@ -0,0 +1,21 @@
+{
+  "colors": {
+    "background": "#f8fafc",
+    "surface": "#ffffff",
+    "text": "#0f172a",
+    "mutedText": "#475569",
+    "border": "#dbe3ee"
+  },
+  "radii": {
+    "panel": 12,
+    "control": 6
+  },
+  "typography": {
+    "bodyFont": "Inter, ui-sans-serif, system-ui, sans-serif",
+    "headingWeight": 760
+  },
+  "spacing": {
+    "pagePadding": 32,
+    "panelPadding": 28
+  }
+}

package/templates/target/reference/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Limner Reference</title>
+    <link rel="stylesheet" href="./styles.css">
+  </head>
+  <body>
+    <main data-limner-region="reference-root" class="limner-reference">
+      <section class="reference-panel">
+        <p class="eyebrow">Limner Reference</p>
+        <h1>Recreate the input image here</h1>
+        <p>
+          Replace this scaffold with faithful HTML and CSS. Add
+          <code>data-limner-region</code> attributes to regions that should be
+          compared against app selectors.
+        </p>
+      </section>
+    </main>
+  </body>
+</html>

package/templates/target/reference/styles.css

@@ -0,0 +1,53 @@
+:root {
+  color-scheme: light;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  color: #0f172a;
+  background: #f8fafc;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: #f8fafc;
+}
+
+.limner-reference {
+  min-height: 100vh;
+  display: grid;
+  place-items: center;
+  padding: 32px;
+}
+
+.reference-panel {
+  width: min(760px, 100%);
+  padding: 28px;
+  border: 1px solid #dbe3ee;
+  border-radius: 12px;
+  background: #ffffff;
+  box-shadow: 0 16px 40px rgba(15, 23, 42, 0.08);
+}
+
+.eyebrow {
+  margin: 0 0 8px;
+  color: #2563eb;
+  font-size: 0.75rem;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+h1 {
+  margin: 0 0 10px;
+  font-size: 2rem;
+  line-height: 1.1;
+}
+
+p {
+  margin: 0;
+  color: #475569;
+  line-height: 1.55;
+}