chore: merge main into feat/sprint-2734-styles-runtime-and-harness

Task A (#49) landed on main while this PR was open and added the same
optional componentStyles field to RuntimeContextSchema plus the
COMPONENT_STYLES_ALLOWLIST constant and a v1→v2 schema version bump in
@domscribe/core. Resolved annotation.ts by taking main's version
(Task A's additions are a functional superset — same shape for
ComponentStylesSchema and componentStyles, plus the version-history
note, the allowlist constant, and ComponentStylesAllowlist type).

All other changes auto-merged cleanly: this PR's StyleCapturer, relay
componentStyles surface, and falsifier harness sit on top of Task A's
build-time style-source attribution.

Note for follow-up: there are now two allowlists living in two places —
COMPONENT_STYLES_ALLOWLIST in @domscribe/core (32 entries from Task A)
and STYLE_CAPTURE_ALLOWLIST in @domscribe/runtime (31 entries from
this PR). They overlap but are not identical. The schema field is
record<string,string> so neither is enforced; this is a documentation/
contract divergence, not a runtime defect. PE/PM should pick one
canonical list in a follow-up.

Post-merge verification (Nx targets on the merge commit):
  - domscribe-core:test     → pass (all suites green, 100% coverage on annotation.ts)
  - domscribe-runtime:test  → pass (548 tests)
  - domscribe-relay:test    → pass
  - domscribe-transform:test → pass
  - typecheck across all 4 → clean
  - lint across all 4      → clean

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Domscribe Staff SWE

packages/domscribe-core/src/lib/migrations/annotation-migrations.spec.ts

@@ -56,15 +56,16 @@ describe('migrateAnnotation', () => {
     expect(result.metadata.schemaVersion).toBe(ANNOTATION_SCHEMA_VERSION);
   });
 
-  it('should default to version 1 when metadata has no schemaVersion', () => {
-    // With ANNOTATION_SCHEMA_VERSION === 1 and no field, readVersion returns 1.
-    // Since 1 === ANNOTATION_SCHEMA_VERSION, no migration steps run — it just stamps.
+  it('should walk legacy (unversioned) data forward to the current version', () => {
+    // readVersion defaults missing metadata.schemaVersion to 1, so a legacy
+    // annotation is migrated through every registered step up to the current
+    // version and then stamped.
     const raw = buildRawAnnotation();
     delete (raw['metadata'] as Record<string, unknown>)['schemaVersion'];
 
     const result = migrateAnnotation(raw);
 
-    expect(result.metadata.schemaVersion).toBe(1);
+    expect(result.metadata.schemaVersion).toBe(ANNOTATION_SCHEMA_VERSION);
   });
 
   it('should default to version 1 when metadata is missing entirely', () => {
@@ -102,4 +103,42 @@ describe('migrateAnnotation', () => {
     expect(result.context.pageUrl).toBe('http://localhost:3000');
     expect(result.context.viewport).toEqual({ width: 1920, height: 1080 });
   });
+
+  it('should migrate a v1 annotation up to v2 (additive, no field rewrite)', () => {
+    // Simulates a v1 annotation persisted before RFC 0001 schema bump.
+    // The v1 → v2 step is purely additive (componentStyles + styleSource
+    // are new optional fields) — the migration must not rewrite or delete
+    // any existing payload data.
+    const raw = buildRawAnnotation({
+      metadata: { schemaVersion: 1 },
+      context: {
+        pageUrl: 'http://localhost:3000',
+        pageTitle: 'Test',
+        viewport: { width: 1920, height: 1080 },
+        userAgent: 'test-agent',
+        runtimeContext: {
+          componentProps: { foo: 'bar' },
+        },
+      },
+    });
+
+    const result = migrateAnnotation(raw);
+
+    expect(result.metadata.schemaVersion).toBe(ANNOTATION_SCHEMA_VERSION);
+    expect(result.context.runtimeContext).toEqual({
+      componentProps: { foo: 'bar' },
+    });
+  });
+
+  it('should leave v1 payloads structurally untouched (forward-compat for v1-pinned clients)', () => {
+    // Forward-compat guarantee for annotation-process.tool: a v1-pinned
+    // downstream consumer reading a v2-migrated annotation sees exactly the
+    // v1 fields it already understood. The new componentStyles slot is
+    // optional and is absent (`undefined`) on migrated v1 payloads.
+    const raw = buildRawAnnotation({ metadata: { schemaVersion: 1 } });
+
+    const result = migrateAnnotation(raw);
+
+    expect(result.context.runtimeContext).toBeUndefined();
+  });
 });

packages/domscribe-core/src/lib/migrations/annotation-migrations.ts

@@ -16,12 +16,22 @@ import {
 /**
  * Registry of migration functions keyed by the version they migrate FROM.
  * e.g. migrationSteps[1] migrates v1 → v2.
- *
- * Currently empty — only v1 exists.  When a v2 schema is introduced, add:
- *   migrationSteps[1] = (data: Record<string, unknown>) => { … mutate … };
  */
 const migrationSteps: Record<number, (data: Record<string, unknown>) => void> =
-  {};
+  {
+    /**
+     * v1 → v2: additive only (per RFC 0001).
+     *
+     * v2 adds optional `runtimeContext.componentStyles` and optional
+     * `manifestSnapshot[].styleSource`. Both are optional and absent on v1
+     * payloads, so no field rewriting is required — the migration step
+     * exists purely to satisfy the version-walk contract and to let v1
+     * annotations be stamped as v2 on next write without throwing.
+     */
+    1: () => {
+      // No-op: v1 → v2 is purely additive.
+    },
+  };
 
 /**
  * Read `metadata.schemaVersion` from raw JSON, defaulting to 1 for

packages/domscribe-core/src/lib/types/annotation.ts

@@ -55,42 +55,47 @@ export const EnvironmentSchema = z.object({
 });
 
 /**
- * Component-style snapshot captured at runtime.
+ * Runtime style snapshot for the annotated element.
  *
- * `computed` is a bounded subset of CSS properties resolved via
- * `getComputedStyle()` against the picked element (see the
- * `STYLE_CAPTURE_ALLOWLIST` in `@domscribe/runtime`). `customProperties` are
- * the resolved `--*` CSS variables visible from the element up to `:root`,
- * used as the runtime token boundary for design-system attribution.
+ * Captured by `@domscribe/runtime` at interaction time when
+ * `domscribe.config.captureStyles` is enabled. Two slots:
  *
- * Both fields are optional so older clients can ignore them. Companion
- * build-time `styleSource` attribution lives on `ManifestEntry` and is
- * intentionally separate — runtime context here is ground truth for what is
- * rendered; the manifest field is ground truth for where it came from.
+ * - `computed`: a fixed allowlist of computed-style properties (≤32 entries
+ *   covering layout, spacing, typography, visual, and positioning). This is
+ *   the ground truth for "what the user sees" — survives conditional class
+ *   names, responsive variants, and runtime theme switches that build-time
+ *   attribution alone cannot resolve.
+ * - `customProperties`: resolved CSS custom properties (`--*` vars) on the
+ *   element and its ancestors up to `:root`. Lets the agent recover the
+ *   design-system token boundary without re-resolving Tailwind config or a
+ *   styled-components theme.
+ *
+ * Both fields are optional. Capture is best-effort and respects the
+ * existing per-element serialization budget (≤4 KB).
  */
 export const ComponentStylesSchema = z.object({
   computed: z
     .record(z.string(), z.string())
     .optional()
     .describe(
-      'Computed CSS properties from the allowlist (≤32 entries: layout, spacing, typography, visual, positioning)',
+      'Subset of computed CSS properties for the element, drawn from a fixed ≤32-property allowlist',
     ),
   customProperties: z
     .record(z.string(), z.string())
     .optional()
     .describe(
-      'Resolved `--*` CSS custom properties visible from the element through its ancestors up to `:root`',
+      'Resolved CSS custom properties (--* variables) inherited by the element from itself up to :root',
     ),
 });
 
 export const RuntimeContextSchema = z.object({
   componentProps: z.unknown().optional().describe('Component props snapshot'),
   componentState: z.unknown().optional().describe('Component state snapshot'),
-  eventFlow: z.unknown().optional().describe('Event flow breadcrumbs'),
-  performance: z.unknown().optional().describe('Performance metrics'),
   componentStyles: ComponentStylesSchema.optional().describe(
-    'Captured computed styles + resolved CSS custom properties for the picked element. Populated when `domscribe.config.captureStyles` is enabled.',
+    'Computed-style allowlist + resolved CSS custom properties (captured when domscribe.config.captureStyles is enabled)',
   ),
+  eventFlow: z.unknown().optional().describe('Event flow breadcrumbs'),
+  performance: z.unknown().optional().describe('Performance metrics'),
 });
 
 export const AnnotationIdSchema = z
@@ -100,8 +105,14 @@ export const AnnotationIdSchema = z
 
 /**
  * Current annotation schema version. Bump when the Annotation shape changes.
+ *
+ * Version history:
+ * - v1: initial schema.
+ * - v2: added optional `runtimeContext.componentStyles` (computed-style
+ *   allowlist + CSS custom properties) and optional `styleSource` on
+ *   embedded `manifestSnapshot` entries, per RFC 0001.
  */
-export const ANNOTATION_SCHEMA_VERSION = 1;
+export const ANNOTATION_SCHEMA_VERSION = 2;
 
 export const AnnotationMetadataSchema = z.object({
   id: AnnotationIdSchema,
@@ -229,3 +240,56 @@ export type Viewport = z.infer<typeof ViewportSchema>;
 export type Environment = z.infer<typeof EnvironmentSchema>;
 export type RuntimeContext = z.infer<typeof RuntimeContextSchema>;
 export type ComponentStyles = z.infer<typeof ComponentStylesSchema>;
+
+/**
+ * Allowlist of computed-style property names captured by the runtime
+ * `StyleCapturer` (≤32 entries). Lives in `@domscribe/core` so the
+ * runtime, the relay, and downstream tools agree on the contract.
+ *
+ * Covers layout, spacing, typography, visual, and positioning — chosen to
+ * be a useful styling-debug subset without bloating the per-element
+ * serialization budget.
+ */
+export const COMPONENT_STYLES_ALLOWLIST = [
+  // Layout
+  'display',
+  'position',
+  'flex-direction',
+  'flex-wrap',
+  'align-items',
+  'justify-content',
+  'gap',
+  'grid-template-columns',
+  'grid-template-rows',
+  // Spacing
+  'margin',
+  'padding',
+  'width',
+  'height',
+  'min-width',
+  'min-height',
+  'max-width',
+  'max-height',
+  // Typography
+  'font-family',
+  'font-size',
+  'font-weight',
+  'line-height',
+  'letter-spacing',
+  'text-align',
+  'color',
+  // Visual
+  'background-color',
+  'border',
+  'border-radius',
+  'box-shadow',
+  'opacity',
+  // Positioning
+  'top',
+  'right',
+  'bottom',
+  'left',
+] as const satisfies readonly string[];
+
+export type ComponentStylesAllowlist =
+  (typeof COMPONENT_STYLES_ALLOWLIST)[number];

packages/domscribe-core/src/lib/types/manifest.ts

@@ -25,6 +25,86 @@ export const StyleInfoSchema = z.object({
   inline: z.string().optional().describe('Inline style content'),
 });
 
+/**
+ * Source-block location for a CSS-in-JS declaration (styled-components or emotion).
+ *
+ * Recorded at transform time for elements rendered by a locally-declared
+ * styled-component (e.g. `const StyledDiv = styled.div\`...\`;` used as
+ * `<StyledDiv>`). Lets agents jump from the runtime DOM back to the
+ * authoring source without re-deriving the binding from a hashed class name.
+ */
+export const CssInJsSourceLocationSchema = z.object({
+  file: z
+    .string()
+    .describe('Source file path containing the styled declaration'),
+  line: z
+    .number()
+    .int()
+    .nonnegative()
+    .describe('Line number of the styled declaration (1-indexed)'),
+  column: z
+    .number()
+    .int()
+    .nonnegative()
+    .describe('Column number of the styled declaration (0-indexed)'),
+  blockText: z
+    .string()
+    .describe(
+      'Verbatim source text of the styled template literal or css block (truncated to 4 KB)',
+    ),
+  library: z
+    .enum(['styled-components', 'emotion', 'unknown'])
+    .optional()
+    .describe('Detected CSS-in-JS library, when statically inferable'),
+  kind: z
+    .enum(['styled-tag', 'styled-call', 'css-template'])
+    .optional()
+    .describe(
+      'AST pattern that matched: styled.div (styled-tag), styled(Component) (styled-call), or css`...` (css-template)',
+    ),
+});
+
+/**
+ * Build-time style attribution for a manifest entry.
+ *
+ * Captured by `@domscribe/transform` on the same AST visit that injects
+ * `data-ds` attributes. Provides the agent with a static link from the
+ * rendered element to the styling source that produced it, so styling-shaped
+ * annotations can be resolved without a runtime round trip for the
+ * source-attribution step.
+ *
+ * @remarks
+ * - `className` is the raw value of the JSX `className` attribute when it is
+ *   statically extractable (string literal or single template literal with
+ *   no interpolations). Computed expressions yield `undefined`.
+ * - `classes` is the array of utility-class tokens statically derivable from
+ *   the `className` expression, including tokens reachable through `clsx`,
+ *   `cn`, `tw`, conditional expressions, and string-only template literals.
+ *   Tokens reachable only through runtime values are silently dropped.
+ * - `cssInJs` is set when the JSX tag references a locally-declared
+ *   styled-component in the same source file.
+ *
+ * All fields are optional: a partial attribution is preferable to a throw,
+ * and absence is the correct signal to fall back to reading the source.
+ */
+export const StyleSourceSchema = z.object({
+  className: z
+    .string()
+    .optional()
+    .describe(
+      'Statically-resolvable className literal as it appears in source; undefined when className is fully computed at runtime',
+    ),
+  classes: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Parsed utility-class tokens reachable statically from the className expression',
+    ),
+  cssInJs: CssInJsSourceLocationSchema.optional().describe(
+    'Source-block location for the CSS-in-JS declaration backing this element',
+  ),
+});
+
 /**
  * Framework-specific component metadata
  */
@@ -73,6 +153,9 @@ export const ManifestEntrySchema = z.object({
     .string()
     .optional()
     .describe('xxhash64 hash of file content at transform time (16 hex chars)'),
+  styleSource: StyleSourceSchema.optional().describe(
+    'Build-time style attribution (className tokens + CSS-in-JS source-block location)',
+  ),
 });
 
 export const ManifestMetadataSchema = z.object({
@@ -107,6 +190,8 @@ export const ManifestIndexSchema = z.object({
 export type SourcePosition = z.infer<typeof SourcePositionSchema>;
 export type StyleInfo = z.infer<typeof StyleInfoSchema>;
 export type ComponentMetadata = z.infer<typeof ComponentMetadataSchema>;
+export type CssInJsSourceLocation = z.infer<typeof CssInJsSourceLocationSchema>;
+export type StyleSource = z.infer<typeof StyleSourceSchema>;
 
 export type ManifestEntryId = z.infer<typeof ManifestEntryIdSchema>;
 export type ManifestEntry = z.infer<typeof ManifestEntrySchema>;

packages/domscribe-relay/src/mcp/tools/manifest-query.tool.ts

@@ -51,7 +51,8 @@ export class ManifestQueryTool implements McpToolDefinition<
     'Query the Domscribe manifest to find UI elements by file, component, or tag name. ' +
     'Use to explore what elements exist in a file ("what\'s in Button.tsx?"), ' +
     'find all instances of a component ("find all Modal elements"), ' +
-    'or list elements by tag ("show all input elements").';
+    'or list elements by tag ("show all input elements"). ' +
+    'Entries include `styleSource` when build-time style capture is enabled (statically-resolvable className tokens + CSS-in-JS source-block location) — useful when triaging a styling annotation before requesting live runtime context.';
   inputSchema = ManifestQueryToolInputSchema;
   outputSchema = ManifestQueryToolOutputSchema;