c0py/docs/spec/DIGITAL-TWIN-SPEC.md

C0PY — Digital Twin Specification

Version: 0.1.0-draft Status: Draft Purpose: Specifies every category of component, data, and relationship that C0PY must capture from a website/product to produce a theoretically identical digital twin — reproducible by autonomous AI agents with full pixel-level fidelity and all functionality.

---

Innehållsförteckning

1. Översikt
2. Definitioner
3. Taxonomi — Kategorier av beståndsdelar
4. Ontologi — Entiteter, attribut, relationer
5. Topologi — Strukturella och rymsliga relationer
6. Designinfångning
7. Medieinfångning
8. Datainsamling
9. Funktionsspecifikation
10. Teknisk infrastruktur
11. Tillgänglighet och internationisering
12. Utdataformat
13. AI-Agent-arkitektur
14. Kvalitetskriterier

---

1. Översikt

C0PY är ett verktyg som konsumerar en webbadress och producerar ett fullständigt register — en digital tvilling — av webbplatsen. Tvillingen måste teoretiskt kunna återskapa varje funktion, variabel utseende, alla data och alla komponenter i identisk form.

Filosofi

• Heltäckande: Ingen kategori av beståndsdel får förbisetas.
• Automatiserad: All infångning utförs av AI-agenter, inte manuellt.
• Maskinläsbar utdata: Allt produceras i strukturerat format (JSON/YAML + mediafiler).
• Pixelnär: Design ska beskrivas så exakt att en identisk kopia kan produceras.
• Funktionellt hela: All interaktivitet,状态, och beteende ska dokumenteras.

Scope

Applicerar på:

• Webbplatser (singelpage, multipage, SPA, MPA)
• Webbsidor (lanseringssidor, produktsidor, bloggar)
• Webbservrar (REST, GraphQL, tider)
• SaaS-gränssnitt (dashboards, admin-paneler)
• E-handel (kataloger, kassaflöden, betalningar)
• Portaler (intranät, kundportaler, operatörsgränssnitt)

---

2. Definitioner

Term	Definition
Källa	Den ursprungliga webbplatsen som ska analyseras
Digital tvilling	C0PYs fullständiga register av källan
Agent	En autonom AI-enhet som utför en specifik infångningsuppgift
Taxonomi	Klassificeringssystem för alla beståndsdelar
Ontologi	Entiteter, deras attribut och relationer
Topologi	Rumsliga och strukturella samband
Komponent	Återkommande UI-enhet med definierat beteende
Mall	Färdig struktur för en komponenttyp med plats för data
Designtoken	Grundläggande designenhet (färg, typografi, spacing)
Yta	Visuellt element som användaren ser och interagerar med
Beteende	Dynamisk respons på händelser eller tillstånd
Dataobjekt	Strukturerad information som visas eller bearbetas
Tillstånd	Aktuellt värde på en variabel vid en given tidpunkt

---

3. Taxonomi — Kategorier av beståndsdelar

3.1 Ytliga designelement (Visual Design Layer)

design/
├── colors/
│   ├── semantic/         (primary, secondary, accent, error, success, warning, info)
│   ├── literal/          (#RRGGBB, rgb, hsl, named)
│   ├── transient/        (hover, active, focus, disabled, visited states)
│   ├── gradients/        (linear, radial, conic — positions, stops)
│   └── opacity/          (alpha values, overlay layers)
├── typography/
│   ├── font-families/    (name, weight, style, source, fallback)
│   ├── type-scale/       (h1-h6, body, caption, overline, monospace)
│   ├── letter-spacing/   (per element type)
│   ├── line-height/      (per element type)
│   └── text-decoration/  (underline, line-through, styles)
├── spacing/
│   ├── padding/          (per component, per breakpoint)
│   ├── margin/           (per component, per breakpoint)
│   ├── gap/              (grid/flex gap values)
│   └── inset/            (inset properties)
├── borders/
│   ├── width/
│   ├── style/            (solid, dashed, dotted, double, groove)
│   ├── color/
│   └── radius/           (per corner, per component)
├── shadows/
│   ├── box-shadow/       (layered, per elevation level)
│   └── text-shadow/
├── backgrounds/
│   ├── color/
│   ├── image/            (url, size, repeat, position, attachment)
│   ├── pattern/          (repeating patterns, textures)
│   └── gradient/
└── animations/
    ├── keyframes/        (name, duration, easing, delay, iteration)
    ├── transitions/      (property, duration, easing, delay)
    └── scroll-effects/   (parallax, sticky, reveal)

3.2 Layout och struktur (Layout Layer)

layout/
├── grid-system/
│   ├── columns/          (count, width, offset)
│   ├── rows/             (height, min/max)
│   ├── gaps/             (row-gap, column-gap)
│   └── responsive-breakpoints/ (width, orientation, media-query)
├── containers/
│   ├── max-width/        (per breakpoint)
│   ├── padding/          (per side, per breakpoint)
│   └── margin/           (auto, fixed, percentage)
├── flex-configurations/  (direction, justify, align, wrap, gap)
├── position-scheme/      (static, relative, absolute, fixed, sticky)
│   └── z-index-stack/    (layer ordering)
├── aspect-ratios/        (per media/container)
└── overflow/             (visible, hidden, scroll, auto)

3.3 Komponenter (Component Layer)

components/
├── navigation/
│   ├── primary-menu/     (items, order, dropdowns, mega-menus)
│   ├── secondary-menu/
│   ├── breadcrumbs/      (items, separators, current indicator)
│   ├── pagination/       (pages, current, prev/next, size)
│   ├── tabs/             (labels, panels, active state)
│   ├── sidebar/          (sections, collapsible, sticky)
│   └── footer/           (columns, links, social, legal)
├── forms/
│   ├── input/            (type, placeholder, validation, size)
│   ├── textarea/         (rows, maxlength, resize)
│   ├── select/           (options, multi, search, grouped)
│   ├── checkbox/         (label, checked, indeterminate, disabled)
│   ├── radio/            (label, selected, group)
│   ├── toggle/           (on/off, label, track, thumb)
│   ├── slider/           (min, max, step, value, range)
│   ├── date-picker/      (format, range, calendar style)
│   ├── file-upload/      (accept, multiple, drag-drop, preview)
│   ├── search/           (input, results, autocomplete, filters)
│   ├── button/           (label, variant, size, icon, loading state)
│   └── form-layout/      (labels, order, sections, help text)
├── feedback/
│   ├── toast/            (message, type, duration, position)
│   ├── snackbar/
│   ├── alert/            (type, icon, dismissable, actions)
│   ├── modal/            (title, content, actions, size, backdrop)
│   ├── dialog/           (form, confirm, info, progress)
│   ├── tooltip/          (content, position, delay)
│   ├── popover/          (content, position, trigger)
│   ├── dropdown/         (options, trigger, search)
│   └── loading/          (spinners, skeletons, progress bars)
├── content/
│   ├── card/             (image, title, subtitle, content, actions)
│   ├── list/             (ordered, unordered, definition, media)
│   ├── table/            (columns, rows, sort, filter, pagination, expand)
│   ├── gallery/          (images, captions, grid, lightbox)
│   ├── media-player/     (video, audio, controls, captions, quality)
│   ├── accordion/        (sections, expanded, animation)
│   ├── timeline/         (events, connectors, orientation)
│   └── tag/              (label, color, removable, count)
├── display/
│   ├── heading/          (level, align, decoration)
│   ├── paragraph/        (align, indent, spacing)
│   ├── quote/            (text, attribution, style)
│   ├── code/             (language, copy, theme, line-numbers)
│   ├── badge/            (text, color, size, shape)
│   ├── stat/             (value, label, trend, format)
│   └── avatar/           (image, initials, size, shape, status)
└── data/
    ├── chart/            (type, data, axes, legend, tooltip, animation)
    ├── graph/            (nodes, edges, layout, interactive)
    ├── map/              (provider, bounds, markers, layers, controls)
    ├── calendar/         (date range, events, view, selectable)
    └── tree/             (nodes, expand, select, checkbox)

3.4 Sidstrukturer (Page Structure Layer)

pages/
├── landing-page/         (hero, features, testimonials, pricing, CTA, stats)
├── product-page/         (gallery, description, specs, reviews, related, buy)
├── category-page/        (filters, grid/list, sort, pagination, count)
├── checkout-flow/        (steps, forms, summary, payment, confirm)
├── dashboard/            (widgets, charts, tables, filters, time-range)
├── login-page/           (form, oauth, forgot, register, mfa)
├── profile-page/         (avatar, info, preferences, security, activity)
├── settings-page/        (sections, toggles, forms, save/cancel)
├── search-results/       (query, filters, sort, results, count, pagination)
├── error-pages/          (404, 500, 403, 401 — design, message, actions)
├── legal/                (terms, privacy, cookies, accessibility)
└── blog/                 (post, listing, category, tag, author, comments)

3.5 Funktionella element (Functional Layer)

functionality/
├── routing/
│   ├── url-patterns/     (path, params, query, hash, canonical)
│   ├── redirects/        (from, to, type, condition)
│   ├── 404/              (design, message, search, suggestions)
│   └── deep-linking/     (shareable, restoreable, bookmarkable)
├── state-management/
│   ├── global-state/     (store, slices, selectors, middleware)
│   ├── local-state/      (component-level, persistence)
│   ├── session-state/    (auth, cart, preferences)
│   └── URL-state/        (query params, hash fragments)
├── API/
│   ├── endpoints/        (method, path, params, body, response)
│   ├── graphql-schema/   (types, queries, mutations, subscriptions)
│   ├── websockets/       (channels, messages, auth, reconnection)
│   └── SSE/              (events, retry, data format)
├── events/
│   ├── user-interaction/ (click, hover, focus, blur, submit, scroll)
│   ├── lifecycle/        (mount, unmount, update, create, delete)
│   ├── network/          (online, offline, reconnect)
│   └── custom/           (domain events, bus events)
├── validation/
│   ├── client/           (format, required, range, custom)
│   ├── server/           (schema, auth, permission, business rules)
│   └── error-format/     (code, message, field, retryable)
└── workflows/
    ├── multi-step/       (steps, current, status, guard, redirect)
    ├── approval/         (requester, approver, levels, evidence)
    └── queued/           (job type, status, retry, dead-letter)

3.6 Dataobjekt (Data Layer)

data/
├── content/
│   ├── text/             (all visible text, language, region, variant)
│   ├── image-alt/        (alt text for every image)
│   ├── link-text/        (anchor text, title, description)
│   └── metadata/         (title, description, keywords, OG, Twitter)
├── structured/
│   ├── products/         (name, price, currency, sku, stock, attributes)
│   ├── orders/           (id, items, totals, status, customer, dates)
│   ├── users/            (name, email, role, profile, preferences)
│   ├── articles/         (title, body, author, date, tags, category)
│   └── settings/         (key, value, type, scope, updated)
├── relationships/
│   ├── parent-child/
│   ├── many-to-many/
│   ├── referral/         (who links to whom, anchor)
│   └── dependency/       (what depends on what)
└── temporal/
    ├── created/          (timestamp, actor, source)
    ├── modified/         (timestamp, actor, field, previous)
    └── deleted/          (soft-delete timestamp, actor, reason)

3.7 Teknisk infrastruktur (Infrastructure Layer)

infrastructure/
├── stack/
│   ├── framework/        (React, Next, Vue, etc. + version)
│   ├── runtime/          (Node, Python, Go + version)
│   ├── build/            (tool, config, output)
│   ├── server/           (Caddy, Nginx, Apache, Cloudflare)
│   └── database/         (Postgres, MySQL, Mongo, Redis + version)
├── performance/
│   ├── bundle-analysis/  (size, chunks, dedup, lazy loading)
│   ├── lighthouse/       (PWA, accessibility, SEO, performance scores)
│   ├── core-web-vitals/  (FCP, LCP, INP, CLS, TTFB)
│   └── budget/           (max size, max load time per asset)
├── security/
│   ├── headers/          (CSP, HSTS, X-Frame, X-Content-Type)
│   ├── auth/             (method, flow, tokens, refresh, expiry)
│   ├── cors/             (origins, methods, headers, credentials)
│   └── rate-limiting/    (rules, headers, response)
└── deployment/
    ├── ci/               (pipelines, triggers, environments)
    ├── cd/               (strategies, rollbacks, health checks)
    └── monitoring/       (errors, performance, uptime, alerts)

---

4. Ontologi — Entiteter, attribut, relationer

4.1 Entitetstyper

Entitet	Supertyp	Sekundära typer
Color	design_token	semantic, literal, transient, opacity, gradient
Typography	design_token	font_scale, type_scale, text_style
Spacing	design_token	padding, margin, gap, inset
Border	design_token	width, style, color, radius
Shadow	design_token	box_shadow, text_shadow
Animation	design_token	keyframe, transition, effect
Component	ui_element	container, content, feedback, navigation, data
Page	layout	landing, product, dashboard, login, error
Section	page_part	hero, features, testimonials, pricing, CTA
Template	structural	grid, flex, absolute, responsive
DataObject	content	text, image, structured, temporal
Route	functionality	static, dynamic, parameter, redirect
Event	behavior	user, lifecycle, network, custom
API	endpoint	REST, GraphQL, WebSocket, SSE
Breakpoint	responsive	mobile, tablet, desktop, wide
MediaAsset	resource	image, video, audio, font, icon, document
DesignSystem	collection	tokens, components, patterns, guidelines
State	variable	global, local, session, URL
Workflow	process	linear, branching, parallel, conditional
ValidationRule	constraint	client, server, format, range, custom

4.2 attribut per entitet (utvalda exempel)

Color:

id: uuid
name: string (semantic_name or hex)
value: string (hex/rgb/hsl/named)
alpha: float (0-1, optional)
type: enum (semantic|literal|transient|opacity|gradient)
state: enum (default|hover|active|focus|disabled|visited)
usedBy: [Component.id]
contrastRatio: float
wcagLevel: enum (AA|AAA|pass|fail)

Component:

id: uuid
type: enum (navigation|form|feedback|content|data|display)
name: string (e.g., "primary-menu", "checkout-modal")
props: JSON (all configurable properties and defaults)
state: JSON (current state values)
styles: { colors, typography, spacing, borders, shadows }
behavior: { events, handlers, transitions }
data: { source, mapping, refresh, caching }
accessibility: { aria, roles, keyboard, focus }
responsive: { breakpoints, adaptations }
composition: [Component.id] (nested components)
parent: Component.id | Page.id
order: int
visibility: { condition, permission, featureFlag }

Page:

id: uuid
url: string
title: string
template: string (layout template name)
sections: [Section.id] (ordered)
components: [Component.id]
meta: { seo, og, twitter, jsonld }
scripts: [{src, async, defer, type}]
styles: [{src, inline, media}]
state: { initial, persisted }
error: { type, design, actions }
i18n: { locale, fallback, rtl }

4.3 Relationer

Composition (strong):
  Page ──contains──> Section
  Section ──contains──> Component
  Component ──contains──> Component
  Component ──renders──> DataObject

Reference (weak):
  Component ──uses──> Color
  Component ──uses──> Typography
  Component ──uses──> Spacing
  Component ──uses──> Border
  Component ──uses──> Shadow
  Component ──uses──> Animation
  Component ──validates──> ValidationRule
  Component ──subscribes──> Event
  API ──returns──> DataObject
  Route ──maps──> Page

Dependency:
  Component ──depends──> Component (loading order)
  Page ──depends──> MediaAsset
  Component ──requires──> State
  Workflow ──includes──> Event

Event-Handling:
  Event ──triggers──> Handler
  Handler ──modifies──> State
  Handler ──calls──> API
  Handler ──navigates──> Route
  Handler ──renders──> Component (conditional)

Temporal:
  DataObject ──createdBy──> Actor
  DataObject ──modifiedBy──> Actor
  DataObject ──versionOf──> DataObject (previous)

---

5. Topologi — Strukturella och rymsliga relationer

5.1 DOM-topologi

root (document)
├── head
│   ├── meta [n]
│   ├── title
│   ├── link [n] (stylesheets, icons, preload)
│   ├── script [n]
│   └── style [n]
└── body
    ├── header (semantic) | [optional]
    │   ├── nav.primary
    │   ├── nav.secondary
    │   └── brand/logo
    ├── main
    │   ├── section.hero | [optional]
    │   ├── section.features | [optional]
    │   ├── section.content | [repeating]
    │   ├── section.sidebar | [optional]
    │   └── section.footer | [optional]
    │       ├── component [n]
    │       └── component [n]
    ├── aside | [optional]
    │   └── component [n]
    └── footer
        ├── nav [n]
        └── component [n]

5.2 CSS-rumslig topologi

viewport
├── block flow (vertical stacking)
│   ├── margin (outside)
│   │   └── border
│   │       └── padding (inside)
│   │           └── content
│   └── inline flow (horizontal)
│       └── flex/grid container
│           └── items [n]
├── position:absolute (removed from flow, positioned by top/right/bottom/left)
├── position:fixed (viewport-relative, persistent)
├── position:sticky (conditional flow + viewport-relative)
└── z-index-stack (layer ordering, paint order)

5.3 Visuell hierarki

elevation/stacking-context:
  base (z: 0)
  dropdown (z: 10)
  sticky-header (z: 50)
  modal-backdrop (z: 100)
  modal-content (z: 101)
  drawer (z: 200)
  toast (z: 1000)
  alert (z: 1001)
  tooltip (z: 2000)

visual-priority:
  primary (largest, boldest, most contrast)
  secondary (medium)
  tertiary (smallest, subdued)
  disabled (low contrast, reduced presence)

5.4 Reaktionsbild-topologi (Responsive)

breakpoints [n]:
  mobile (max-width: 767px):
    layout: single-column
    navigation: hamburger/drawer
    typography: scale-factor 0.85
    spacing: scale-factor 0.75
    images: responsive, srcset variants
  tablet (768px–1023px):
    layout: 2-column where applicable
    navigation: expanded or hamburger
    typography: scale-factor 0.95
    spacing: scale-factor 0.875
  desktop (1024px–1439px):
    layout: full grid (e.g., 12-col)
    navigation: full horizontal
    typography: scale-factor 1.0
    spacing: base values
  wide (min-width: 1440px):
    layout: constrained-width centered
    navigation: full + mega-menu
    typography: scale-factor 1.05
    spacing: scale-factor 1.05

---

6. Designinfångning

6.1 Designsystemupptäckt

Agenterna ska automatiskt upptäcka och definiera:

6.1.1 DesignToken-katalog

Per upptäckt:
- Token-name (conventionell, t.ex. "color-primary", "space-md")
- Token-värde (exakt, inklusive enhet)
- Token-typ (color, typography, spacing, border, shadow, animation)
- Token-status (draft, stable, deprecated)
- Token-beskrivning (varför existerar den, användning)
- Token-användning (var används den, hur ofta)
- Token-relaterade (varianter, delmängder, superord)

6.1.2 Identifieringsmetod

• Sortera designtokens efter frekvens (vad som förekommer mest)
• Identifiera primära (används > 5 ställen) → sekundära (2-4) → enskilda (1)
• Gröna (används > 10 ställen), gula (2-10), röda (1) — rekommenderar konsolidering
• Identifiera "utanför" variationer som eventuellt förväxlar systemet → flagga för granskning

6.2 Automatisk designanalys

För varje sida:
1. Skanna all synlig UI (DOM + renderat)
2. Extrahera alla designtokens (färger, typografi, spacing, etc.)
3. Gruppera efter typ och namn
4. Identifiera inkonsekvenser (samma funktion, olika namn/värde)
5. Identifiera brist på system (varierad margin mellan liknande element)
6. Producera designtoken-katalog med förslag till standardisering

---

7. Medieinfångning

7.1 Bilder

Per bild:
- src (ursprunglig url)
- formats: [jpeg, png, webp, avif, svg, gif, heic]
- dimensions: {width, height} (px)
- aspect-ratio: W:H
- alt-text (bildtext för tillgänglighet)
- srcset: [{width, url}, ...] (responsiva varianter)
- sizes: string (CSS sizes attribute)
- loading: enum (eager|lazy)
- decoding: enum (async|sync|auto)
- content-color: dominerande färg (för fade-in LCP)
- position: {page, section, component, order}
- crop: {type, focal-point-x, focal-point-y}
- background: {color-fallback}
- dpr-variants: [{dpr, url, dimensions}]

7.2 Video

Per video:
- src (primär url)
- formats: [mp4, webm, ogg]
- poster: {url, dimensions}
- dimensions: {width, height}
- aspect-ratio
- autoplay, muted, loop, controls, preload
- caption-tracks: [{src, language, kind, default}]
- chapters: [{start-time, label}]
- thumbnails: [{time, url}]
- lazy: boolean
- position: {page, section, component, order}

7.3 Ikonografie

Per ikon:
- name/label (tillägnad, beskrivande)
- format: [svg-png, icon-font, icon-library]
- dimensions: {width, height} (px, 16/20/24/32/48/64 etc.)
- color: {default, hover, active, disabled}
- weight: {regular, thin, bold, filled, outlined}
- library: [phosphor, heroicons, lucide, fontawesome, custom]
- glyph-id (och unicode om icon-font)
- position: {page, component, context}
- alternative-spellings: [synonyma varianter]
- aliasing: {duplicate-detection, canonical}

7.4 Typsnitt

Per typsnitt:
- family-name: string
- weight: [100-900, italic/normal]
- style: [normal, italic, oblique]
- unicode-range: string
- format: [woff2, woff, ttf, otf, eot]
- src: url
- font-display: [auto|block|swap|fallback|optional]
- variable: boolean (var font)
- axes: [{axis-tag, min, max, default}]
- subset: [latin, latin-ext, cyrillic, etc.]
- size-adjust: float (per fallbackskrift)
- ascent-override, descent-override: float
- unicode-range: string
- system-fallback: [font1, font2, ...]

7.5 Andra resurser

CSS/JS:
- src, type, media, async, defer, integrity, preload, prefetch

Documents:
- PDF, DOCX, etc. — url, size, language, description

Favicon/Manifest:
- manifest.json (name, short_name, icons, theme, orientation)
- apple-touch-icon, mask-icon, tile-image
- favicon.ico, favicon-16x16, favicon-32x32, etc.

Fonts-in-use:
- All varianter som faktiskt används (detected via computed styles)
- Fallback chains per font-family

---

8. Datainsamling

8.1 Innehållsinsamling

Per sida:
1. All synlig text (detekterad per element, i DOM-ordning)
   - Språkidentifiering (ISO 639-1 per text-block)
   - Texttyp (heading, body, caption, button, label, error)
   - Kontext (var texten förekommer, vilken komponent)
   - Längd (tecken, ord, rader)
   - Variant (om flera varianter existerar, t.ex. A/B test)

2. All bildtext (alt, title, src-set description)

3. All länktext och mål
   - Interna/externa
   - Anchor text, title attribute
   - Visa/skriv typ (icon, text, combined)

4. Metadata
   - page.title, page.description
   - og:title, og:description, og:image
   - twitter:card, twitter:title, twitter:description
   - schema.org/JSON-LD (full structure)
   - twitter:meta, fb:meta

8.2 Strukturerad datainsamling

Per dataobjekt:
- Schema (fält, typer, validering, relationalitet)
- Data (exemplen som faktiskt finns i produktion)
- API-källa (var data hämtas)
- Renderingssätt (direkt, kundtjänst, API, statisk)
- Cache-strategi (TTL, invalidation)
- Persistens (var och hur lagras)
- Behörighet (vem kan se, ändra, radera)
- Version (om det finns versionshantering)

8.3 URL-strukturinsamling

Per sida/endpoint:
- URL (fullständig, kanonical)
- Metod (GET, POST, PUT, DELETE, PATCH)
- Parameter (path, query, header, body)
- Response (status, body, headers, cache)
- Parameter-schema (namn, typ, required, default, validering)
- Auth-behov (anonymous, authenticated, role)
- Rate-limit (om tillämpligt)
- Relaterade URLs (prev, next, related, parent)

---

9. Funktionsspecifikation

9.1 Beteende-specifikation

För varje interaktiv element:

Element-specifikation:
- Trigger (händelse som orsakar förändring)
- Precondition (tillstånd krävs för att utlösas)
- Action (vad som händer)
- Effect (synlig förändring)
- Side-effect (API-anrop, navigation, tillståndsförändring)
- Error-path (vad händer vid fel)
- Loading-state (visas under bearbetning)
- Empty-state (visas när inget finns)
- Disabled-state (tillgänglighet vid inaktiv)
- Undo/Redo (om möjligt, återställningssätt)
- Keyboard-shortcut (tillgänglighet)
- Touch/Gesture (mobile interaktion)

9.2 Tillståndsmaskin-specifikation

Per tillståndsmaskin:
- States (namn, typ: idle, loading, success, error, empty, disabled)
- Transitions (from, to, trigger, guard, action)
- Initial state
- Final states (terminals)
- History (back/forward support)
- Persistence (session, localStorage, cookie)

9.3 API-kontraktsspecifikation

Per endpoint:
- Method
- URL (inklusive parametrar)
- Auth (Bearer, API-Key, OAuth, Session)
- Request (headers, body schema, query params, path params)
- Response (status codes, body schema, headers)
- Error format
- Idempotens (yes/no, key format)
- Rate limit (requests/minute, burst)
- Versioning (URL, header, query)
- Deprecation (if deprecated, since, removal date)
- Bearer format (JWT claims, token type, expiry)

---

10. Tillgänglighet och internationisering

10.1 Tillgänglighet (WCAG)

Per sida/komponent:
- WCAG nivå (A, AA, AAA)
- ARIA-label (om tillämpligt)
- ARIA-roll (heading, navigation, main, alert, dialog, etc.)
- ARIA-status (live region, polite, assertive)
- Fokus-kort (tab order, visible focus)
- Tangentbordsnavigering (shortcuts, skip-links)
- Färg-kontrast (förhållande, nivå)
- Text-alternativ (bildtext, text-alternativ för video/audio)
- Flashing (seizure-säkerhet)
- Form-validering (error association, live regions)

10.2 Internationisering (i18n)

Språkdata:
- supported-locales: [locale-code, ...]
- default-locale
- rtl-locales: [locale-code, ...]
- Translations: {key: {locale: value, ...}, ...}
- Pluralization rules (per locale)
- Date/time format (per locale)
- Number/currency format (per locale, precision, separator)
- Address format (per locale, fields, order)
- Name format (per locale, order, titles)
- Direction: ltr | rtl | auto (per locale)

---

11. Utdataformat

11.1 Katalogen Struktur

Allt produceras i en katalog som är maskinläsbar och omfattande:

c0py-output/
├── manifest.json           (overgripande information om källan)
├── schema/                 (ontologi, typer, relationer)
│   ├── entities.json       (entitetstyper och attribut)
│   ├── relations.json      (relationschema)
│   └── enums.json          (uppräknade typer)
├── design/                 (designsystem och tokens)
│   ├── tokens.json         (alla designtokens)
│   ├── components.json     (komponentspecifikation)
│   └── pages.json          (sidstruktur)
├── media/                  (nerladdade mediafiler)
│   ├── images/             (bilder med metadata)
│   ├── fonts/              (typsnittsfiler)
│   ├── icons/              (ikonfiler)
│   ├── videos/             (videofiler)
│   └── documents/          (dokumentfiler)
├── content/                (all text och data)
│   ├── text/               (textblock med metadata)
│   ├── data/               (strukturerad data)
│   └── metadata/           (SEO, OG, meta)
├── functionality/          (beteende och funktioner)
│   ├── routes.json         (url-struktur)
│   ├── api.json            (API-kontrakt)
│   ├── state.json          (tillståndsmaskiner)
│   └── events.json         (händelser och handläggare)
├── infrastructure/         (teknisk info)
│   ├── stack.json          (teknikstack)
│   ├── security.json       (säkerhetskonfiguration)
│   └── performance.json    (prestanda data)
└── topology/               (rumsliga strukturer)
    ├── dom.json            (DOM-träd)
    ├── css.json            (CSS-struktur)
    └── layout.json         (layouttopologi)

11.2 Manifestformat

{
  "version": "0.1.0",
  "source": "https://example.com",
  "capturedAt": "2026-09-16T13:00:00Z",
  "agentRunId": "uuid",
  "pages": [
    {
      "url": "/",
      "title": "Home",
      "status": 200,
      "contentType": "text/html",
      "depth": 0,
      "discoveredAt": "...",
      "sections": [...],
      "components": [...],
      "metadata": {...},
      "i18n": {...}
    }
  ],
  "designTokens": [...],
  "mediaAssets": [...],
  "dataObjects": [...],
  "apiEndpoints": [...],
  "infrastructure": {...},
  "topology": {...},
  "statistics": {
    "totalPages": 42,
    "totalComponents": 312,
    "totalMediaAssets": 158,
    "totalTextBlocks": 1047,
    "totalApiEndpoints": 24,
    "totalDataObjects": 56,
    "totalDesignTokens": 89,
    "captureDuration": "PT2H30M"
  }
}

11.3 Media-namnkonvention

media-{type}-{hash-originalname}.{ext}
t.ex. media-image-a3f8b2c1-hero-banner.webp

11.4 ID-konventioner

Alla ID:er i dataset:

• UUID v4 för entiteter
• [type]-[name] för designtokens
• [type]-[slug] för sidor och komponenter
• Konsekvent i alla filer

---

12. AI-Agent-arkitektur

12.1 Övergripande arbetsflöde

Trigger: URL som anges av användaren

Phase 1: DISCOVERY (Upptäckt)
├── Agent: SiteMapAgent
│   ├── Crawl alla sidor (djup-begränsad, breadth-first)
│   ├── Identifiera template-typer
│   ├── Identifiera unika komponenter
│   ├── Bygga URL-väg (alla upptäckta URL:er)
│   ├── Identifiera dynamiska rutter (parametriserade URL:er)
│   └── Producera sitemap.json
├── Agent: TechAgent
│   ├── Identifiera teknikstack (framework, runtime, server)
│   ├── Identifiera CDN, DNS, SSL config
│   ├── Identifiera build-tool, bundler, output
│   └── Producera infrastructure.json
└── Agent: DataAgent
    ├── Identifiera API-endpoints (OpenAPI, Swagger, schema)
    ├── Identifiera GraphQL schema (introspection)
    ├── Identifiera dataobjekt och relationer
    └── Producera api.json + data.json

Phase 2: ANALYSIS (Analys)
├── Agent: DesignAgent
│   ├── Analysera färger → designtoken-katalog
│   ├── Analysera typografi → typografispecifikation
│   ├── Analysera spacing → spacing-specifikation
│   ├── Analysera komponenter → komponentspecifikation
│   ├── Identifiera designmönster → patterns
│   └── Producera design.json
├── Agent: ContentAgent
│   ├── Extrahera all text → content.json
│   ├── Extrahera all metadata → metadata.json
│   ├── Extrahera all data → data.json
│   └── Identifiera i18n → i18n.json
├── Agent: MediaAgent
│   ├── Hämta alla bilder (med format, storlek, metadata)
│   ├── Hämta alla ikoner (med format, storlek, stil)
│   ├── Hämta alla typsnitt (med format, format, källa)
│   ├── Hämta alla videor
│   └── Producera media-manifest + nerladda mediafiler
└── Agent: TopologyAgent
    ├── Bygga DOM-träd → dom.json
    ├── Analysera CSS → css.json
    ├── Bygga layouttopologi → layout.json
    └── Identifiera breakpoints → responsive.json

Phase 3: SYNTHESIS (Syntes)
├── Agent: SpecAgent
│   ├── Samla alla analyser
│   ├── Identifiera inkonsekventer → spec-fynd
│   ├── Bygga komplett designsystem-specifikation
│   ├── Bygga komplett funktionsspecifikation
│   ├── Bygga komplett datamodell
│   └── Producera spec.json + spec.md
├── Agent: QualityAgent
│   ├── Validera fullständighet (saknade kategorier?)
│   ├── Kontrasträkning (WCAG-förhållande)
│   ├── Konsistenskoll (design-inkonsekvenser)
│   ├── Funktionsfullständighet (alla interaktioner registrerade?)
│   └── Producera kvalitetsrapport
└── Agent: AssemblyAgent
    ├── Samla alla filer i utdata-katalog
    ├── generera manifest.json
    ├── validera ID-konventioner
    ├── validera schema-konsekvens
    └── Producera slutgiltig k0py-digitalt-vapen.zip

Phase 4: VERIFICATION (Verifiering)
├── Agent: ReplayAgent
│   ├── Läsa in katalog
│   ├── Tillverka visuell representation (screenshot-mock)
│   ├── Jämför med källan (om tillgänglig)
│   ├── Identifiera luckor
│   └── Förbättra iteration (loop till As-II om nödvändig)
└── Agent: AuditAgent
    ├── Kontrollera att inga kategorier saknas
    ├── Kontrollera att alla ID är unika och konsekventa
    └── Producera certifikat (eller förbättringsrekommendationer)

12.2 Agent-kontrakt

agent:
  name: string
  description: string
  inputs:
    - name: string
      type: string
      required: boolean
      schema: JSONSchema
  outputs:
    - name: string
      type: string
      schema: JSONSchema
  capabilities:
    - crawl
    - analyze
    - synthesize
    - verify
  error-handling:
    retry: {count, delay, backoff}
    fallback: string
    escalation: string
  timeout: PT1H

12.3 Konkurrens och samordning

• Phase 1-agenter körs parallellt (upptäckandet kan delas oberoende)
• Phase 2-agenter beror på Phase 1 och körs parallellt
• Phase 3-agenter beror på Phase 2 och körs sekventiellt (SpecAgent först)
• Phase 4 körs efter Phase 3 och kan trigga omloopning
• Alla agent-utdata skrivs till gemensam datalager med ID-baserad adressering
• Locking: ingen agent skriver till samma fil samtidigt

12.4 Prompt-mall för agentspecifika uppgifter

Du är en C0PY-analysagent. Ditt uppdrag:

MÅL: [specifikt mål]
KÄLLA: [url eller data]
OUTPUT_SCHEMA: [filnavn och schema]

STRATEGI:
1. [Steg-för-steg beskrivning av analysmetod]
2. [Systematisk genomföring]

VALIDERING:
- Kontrollera [kriterier]
- Varför [kriterier]
- Om [undantag] → [åtgärd]

OUTPUT FORMAT:
[för detaljerad beskrivning av utdata]

FÄLLOR ATT UNDVIKA:
- [Vanliga fel för denna analys]
- [Kännedom om webbplatser som är svåra att analysera]

BESKRIV ALLT PÅ FÖRRA NIVÅ NÄR SOM HELST:
[Anvisningar om hur detaljerad beskrivningen ska vara]

SLUTLIGEN, producera [filename.json]:
{schema}

---

13. Kvalitetskriterier

13.1 Fullständighetskriterier

MINSTAKRA:
- Alla URL:er på källan upptäckta och beskrivna (inriktningsgrad > 99%)
- Alla synliga komponenter upptäckta och klassificerade (> 98%)
- Alla designtokens upptäckta och katalogiserade (> 95%)
- Alla mediafiler identifierade (> 95%, undantag: external CDN)
- Alla API-endpoints identifierade (> 90%)
- Alla dataobjekt identifierade (> 90%)
- Alla funktioner beskrivna (> 95%)
- Alla tillståndsmaskiner dokumenterade (> 90%)
- Tillgänglighetskrav kontrollerade för alla komponenter (100%)

13.2 Noggrannhetskriterier

DESIGN:
- Färgvärden: exakta (hex/rgb matchning 100%)
- Typografi: exakt (font, size, weight, line-height matchning 100%)
- Spacing: exakt (margin, padding matchning ±1px)
- Position: exakt (layout matchning ±1px)

DATA:
- Text: ordagrunt exakt (källmatchning 100%)
- Strukturerad data: fält-namn och typer exakt
- API: statuskoder, parametrar, responsformat 100%

FUNKTION:
- Event-handlers: fullständig uppräkning
- Tillståndsmaskiner: alla stater och övergångar
- Villkor: alla synliga/oscilla tillstånd dokumenterade

13.3 Maskinläsbarhetskriterier

- All utdata i giltig JSON/YAML
- Alla ID konsekventa och unika
- Alla referenser giltiga (ingen dubblett, ingen brygga)
- Schema-inre konsistens (inga spruckna referenser)
- Inga tvära avbrott i katalogstrukturen
- Varje entitet har minst: id, typ, namn, beskrivning

---

14. Gränssnitt och icke-funktionskrav

14.1 Performance

- Crawling: maximalt 100 sidor/minut (respekterar robots.txt)
- Analys: maximalt 5 minuter per sida
- Total körning: maximalt 1 timme för upp till 500 sidor
- Agent timeout: 1 timme per agent
- Minnesanvändning: maximalt 4 GB per agent

14.2 Säkerhet

- Inga inmatade secrets ska lagras eller loggas
- Alla media hämtas via autentiserade kanaler
- Inga XSS-risker i analysagenternas hantering av innehåll
- Robots.txt respekteras strikt
- Rate-limits respekteras strikt
- Alla anrop är idempotent och kan avbrytas säkert

14.3 Driftsäkerhet

- Varje agent kan starta om utan förlust (checkpoint var 5 minut)
- Agent-fel försöker maximalt 3 gånger med exponential backoff
- Övervakning av alla agent-ögon (hjärtslag + loggning)
- Fel i en agent påverkar inte andra (isolation)

---

Anhang

A. Referensstrukturer

• WCAG 2.2 AA/AAA för tillgänglighet
• RFC 9110 för HTTP
• OpenAPI 3.1 för API-kontrakt
• JSON Schema Draft 2020-12 för data-schema
• CSS Box Model specifikation för layout
• Material Design / Carbon Design System för komponentmönster

B. Utvecklingslogik

Vers	Datum	Beskrivning
0.1.0	2026-XX-XX	Initial specifikation

C. Offentliga beslut

ID	Beslut	Status
DEC-001	C0PY ska producera maskinläsbar digital tvilling	Fastställd
DEC-002	Allt infångning ska vara automatiskt via AI-agenter	Fastställd
DEC-003	Utdataformat ska vara JSON + mediafiler	Fastställd
DEC-004	Tillgänglighet ska verifieras i varje produktion	Pågående
DEC-005	Agent-arkitektur ska vara parallell och isolerad	Fastställd

---

Denna specifikation är en levande dokument och uppdateras löpande baserat på produktionsfunn och brukaranmälningar.