# @avocadostudio-ai/migration-sdk

Utilities for getting an existing website *into* the Avocado Studio content
shape: scrape a live page, segment it into sections, extract its design tokens,
and generate block definitions from what is there.

This is tooling for a one-time migration, not a runtime dependency of an
integrated site.

## Install

```bash
npm install @avocadostudio-ai/migration-sdk
```

`playwright` is an optional peer, required only by the functions that drive a
real browser (`fetchPageContent`, `takeScreenshot`, `scrapeFullPage`,
`discoverSitePages`). Install it if you use them:

```bash
npm install -D playwright && npx playwright install chromium
```

## What it does

| Area | Functions |
|---|---|
| **Scraping** | `fetchPageContent`, `scrapeFullPage`, `discoverSitePages`, `takeScreenshot`, `downloadImage` |
| **Structure** | `extractSections`, `extractPageOutline`, `extractNavigation`, `segmentByVisualGaps`, `detectRepeatedPatterns`, `resolveLazyImages` |
| **Design** | `extractDesignTokens`, `mapToThemeVariables`, `augmentThemeFromComputedStyles` |
| **Codegen** | `buildSectionSpec`, `buildPageSpecs`, `generateBlock`, `regenerateManifest` |

The intended order is scrape → segment → spec → generate: pull the rendered
page, cut it into candidate sections, describe each one as a spec, and emit a
block definition and renderer from that.

## Why the sections are found visually

A migration cannot trust the source markup to tell it where a section begins —
plenty of sites have one `<div>` per page and plenty have forty per section.
`segmentByVisualGaps` and `detectRepeatedPatterns` work from the rendered
geometry instead, which is why the browser peer exists.

## Design tokens

`extractDesignTokens` reads the site's own CSS custom properties;
`augmentThemeFromComputedStyles` fills the gaps from what the browser actually
computed, for a site that hardcodes its colours. `mapToThemeVariables` turns the
result into Avocado's theme shape.

## License

Apache-2.0