@visual-layer/core 1.0.0

package/dist/schema/index.js

@@ -0,0 +1,96 @@
+/**
+ * ScreenGraph schema — the canonical v0 data contract.
+ *
+ * See VISION_LAYER_MVP_PLAN.md §6 and §18.2 for the accepted contract decisions:
+ *  - bbox is always [x, y, width, height] in the declared coordinate space.
+ *  - confidence is always a finite number in [0, 1].
+ *  - compare_graphs output fields are missingFromActual / extraInActual.
+ */
+import { z } from 'zod';
+/* ---------- primitives ---------- */
+/** `[x, y, width, height]`. width/height must be non-negative. */
+export const Bbox = z
+    .tuple([z.number().finite(), z.number().finite(), z.number().min(0).finite(), z.number().min(0).finite()])
+    .refine((b) => Number.isFinite(b[0]) && Number.isFinite(b[1]), { message: 'bbox origin must be finite' });
+export const CoordinateSpace = z.enum(['viewport', 'screenshot', 'figma']);
+export const ScreenGraphSource = z.enum(['browser', 'figma', 'image', 'hybrid']);
+export const InteractableSource = z.enum(['dom', 'ax', 'figma', 'ocr', 'vision']);
+export const WarningSeverity = z.enum(['info', 'warning', 'error']);
+/** Finite number in [0, 1]. */
+export const Confidence = z.number().finite().min(0).max(1);
+/** Per-dimension grounding scores, each in [0, 1]. */
+export const ScoreBreakdown = z
+    .object({
+    text: z.number().min(0).max(1).optional(),
+    role: z.number().min(0).max(1).optional(),
+    bbox: z.number().min(0).max(1).optional(),
+    source: z.number().min(0).max(1).optional(),
+})
+    .catchall(z.number().min(0).max(1));
+/* ---------- structural types ---------- */
+export const Viewport = z.object({
+    width: z.number().min(0).finite(),
+    height: z.number().min(0).finite(),
+    dpr: z.number().positive().finite().optional(),
+    url: z.string().optional(),
+});
+export const Screenshot = z.object({
+    artifactId: z.string().min(1),
+    sha256: z.string().length(64),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    mimeType: z.enum(['image/png', 'image/jpeg']),
+});
+export const AttributeValue = z.union([z.string(), z.number(), z.boolean()]);
+export const Interactable = z.object({
+    id: z.string().min(1),
+    role: z.string().optional(),
+    name: z.string().optional(),
+    text: z.string().optional(),
+    bbox: Bbox,
+    coordinateSpace: CoordinateSpace,
+    source: z.array(InteractableSource).min(1),
+    confidence: Confidence,
+    domPath: z.string().optional(),
+    axRef: z.string().optional(),
+    figmaNodeId: z.string().optional(),
+    attributes: z.record(z.string(), AttributeValue).optional(),
+});
+export const Warning = z.object({
+    code: z.string().min(1),
+    message: z.string().min(1),
+    severity: WarningSeverity,
+    targetId: z.string().optional(),
+});
+export const Provenance = z.object({
+    /** Dotted path to the field this provenance describes, e.g. `interactables[3].bbox`. */
+    field: z.string().min(1),
+    /** Origin of the value. Either a known source or a free-form adapter label. */
+    source: z.union([InteractableSource, z.string().min(1)]),
+    confidence: Confidence.optional(),
+    note: z.string().optional(),
+});
+/* ---------- graph ---------- */
+/**
+ * The MVP freezes domNodes / axNodes / figmaNodes / ocrBlocks / mappings as
+ * opaque `unknown[]` — adapters may attach raw upstream payloads, but core
+ * only reasons over `interactables`. Concrete shapes land in later versions.
+ */
+export const ScreenGraph = z.object({
+    id: z.string().min(1),
+    version: z.literal('0.1'),
+    source: ScreenGraphSource,
+    createdAt: z.string().min(1),
+    viewport: Viewport.optional(),
+    screenshot: Screenshot.optional(),
+    interactables: z.array(Interactable),
+    domNodes: z.array(z.unknown()).optional(),
+    axNodes: z.array(z.unknown()).optional(),
+    figmaNodes: z.array(z.unknown()).optional(),
+    ocrBlocks: z.array(z.unknown()).optional(),
+    mappings: z.array(z.unknown()).default([]),
+    warnings: z.array(Warning).default([]),
+    provenance: z.array(Provenance).default([]),
+});
+export const SCHEMA_VERSION = '0.1';
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"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"}

package/dist/text/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Text primitives shared by grounding, compare, and adapters.
+ * Core owns these so no other package reinvents them (§18.2).
+ */
+/** Lowercase, collapse whitespace, trim surrounding punctuation/whitespace. */
+export declare function normalizeText(input: string): string;
+/** Split normalized text into non-empty word tokens. */
+export declare function tokenizeText(input: string): string[];
+/**
+ * Deterministic text similarity in [0, 1].
+ *  - exact match (after normalize): 1
+ *  - token-set Jaccard otherwise, with a substring-containment bonus
+ *  - empty/whitespace inputs: 0
+ */
+export declare function compareText(a: string, b: string): number;
+/** Token overlap count (for reading-order / duplicate-label detection). */
+export declare function tokenOverlap(a: string, b: string): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/text/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/text/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIpD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAqBxD;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAMzD"}

package/dist/text/index.js

@@ -0,0 +1,60 @@
+/**
+ * Text primitives shared by grounding, compare, and adapters.
+ * Core owns these so no other package reinvents them (§18.2).
+ */
+/** Lowercase, collapse whitespace, trim surrounding punctuation/whitespace. */
+export function normalizeText(input) {
+    return input
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '')
+        .trim();
+}
+/** Split normalized text into non-empty word tokens. */
+export function tokenizeText(input) {
+    return normalizeText(input)
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Deterministic text similarity in [0, 1].
+ *  - exact match (after normalize): 1
+ *  - token-set Jaccard otherwise, with a substring-containment bonus
+ *  - empty/whitespace inputs: 0
+ */
+export function compareText(a, b) {
+    const na = normalizeText(a);
+    const nb = normalizeText(b);
+    if (na.length === 0 || nb.length === 0)
+        return 0;
+    if (na === nb)
+        return 1;
+    const ta = new Set(tokenizeText(a));
+    const tb = new Set(tokenizeText(b));
+    if (ta.size === 0 || tb.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of ta)
+        if (tb.has(t))
+            inter++;
+    const unionSize = ta.size + tb.size - inter;
+    const jaccard = unionSize === 0 ? 0 : inter / unionSize;
+    // substring bonus: "save changes" inside "click save changes button"
+    let bonus = 0;
+    if (na.length >= 3 && nb.length >= 3) {
+        if (na.includes(nb) || nb.includes(na))
+            bonus = 0.15;
+    }
+    return Math.min(1, jaccard + bonus);
+}
+/** Token overlap count (for reading-order / duplicate-label detection). */
+export function tokenOverlap(a, b) {
+    const ta = new Set(tokenizeText(a));
+    const tb = new Set(tokenizeText(b));
+    let n = 0;
+    for (const t of ta)
+        if (tb.has(t))
+            n++;
+    return n;
+}
+//# sourceMappingURL=index.js.map

package/dist/text/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/text/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK;SACT,WAAW,EAAE;SACb,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,OAAO,CAAC,mCAAmC,EAAE,EAAE,CAAC;SAChD,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,aAAa,CAAC,KAAK,CAAC;SACxB,KAAK,CAAC,iBAAiB,CAAC;SACxB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjD,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,CAAC,CAAC;IAExB,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,EAAE,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE7C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,KAAK,EAAE,CAAC;IAC3C,MAAM,SAAS,GAAG,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC;IAC5C,MAAM,OAAO,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC;IAExD,qEAAqE;IACrE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,KAAK,GAAG,IAAI,CAAC;IACvD,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC,CAAC;AACtC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,CAAC,EAAE,CAAC;IACvC,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/trace/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Run-level trace. `.visual-layer/artifacts/<runId>/trace.json` records the
+ * ordered steps, metrics, and structured errors of a capture/ground/compare run.
+ *
+ * Size budget (§18.8): warn at 256 KiB, truncate nonessential payloads over
+ * 512 KiB while always preserving structured errors and metrics.
+ */
+import type { ArtifactStore } from '../artifact-store/index.js';
+export type TraceLevel = 'info' | 'warn' | 'error' | 'metric';
+export interface TraceEvent {
+    step: string;
+    ts: string;
+    level: TraceLevel;
+    /** Arbitrary structured payload. Subject to truncation. */
+    data?: unknown;
+    /** Structured error — always preserved. */
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    /** Named metric — always preserved. */
+    metric?: {
+        name: string;
+        value: number;
+        unit?: string;
+    };
+}
+export interface TraceOptions {
+    warnBytes?: number;
+    truncateBytes?: number;
+}
+export declare class Trace {
+    readonly runId: string;
+    private events;
+    readonly warnBytes: number;
+    readonly truncateBytes: number;
+    private warned;
+    constructor(runId: string, opts?: TraceOptions);
+    event(e: Omit<TraceEvent, 'ts'>): void;
+    info(step: string, data?: unknown): void;
+    warn(step: string, message: string, data?: unknown): void;
+    error(step: string, err: {
+        code: string;
+        message: string;
+        details?: unknown;
+    }): void;
+    metric(step: string, name: string, value: number, unit?: string): void;
+    /** Serialize with truncation. Returns { json, truncated, bytes }. */
+    serialize(): {
+        json: string;
+        truncated: boolean;
+        bytes: number;
+        warned: boolean;
+    };
+    flush(store: ArtifactStore): Promise<{
+        bytes: number;
+        truncated: boolean;
+        warned: boolean;
+    }>;
+    getEvents(): readonly TraceEvent[];
+    private dump;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/trace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/trace/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2CAA2C;IAC3C,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7D,uCAAuC;IACvC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzD;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAOD,qBAAa,KAAK;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,MAAM,CAAoB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,MAAM,CAAS;gBAEX,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB;IAMlD,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,IAAI;IAItC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAIxC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAIzD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAIpF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAItE,qEAAqE;IACrE,SAAS,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE;IAsB3E,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAMlG,SAAS,IAAI,SAAS,UAAU,EAAE;IAIlC,OAAO,CAAC,IAAI;CAGb"}

package/dist/trace/index.js

@@ -0,0 +1,63 @@
+const DEFAULTS = {
+    warnBytes: 256 * 1024,
+    truncateBytes: 512 * 1024,
+};
+export class Trace {
+    runId;
+    events = [];
+    warnBytes;
+    truncateBytes;
+    warned = false;
+    constructor(runId, opts = {}) {
+        this.runId = runId;
+        this.warnBytes = opts.warnBytes ?? DEFAULTS.warnBytes;
+        this.truncateBytes = opts.truncateBytes ?? DEFAULTS.truncateBytes;
+    }
+    event(e) {
+        this.events.push({ ...e, ts: new Date().toISOString() });
+    }
+    info(step, data) {
+        this.event({ step, level: 'info', data });
+    }
+    warn(step, message, data) {
+        this.event({ step, level: 'warn', data: data ?? { message } });
+    }
+    error(step, err) {
+        this.event({ step, level: 'error', error: err });
+    }
+    metric(step, name, value, unit) {
+        this.event({ step, level: 'metric', metric: { name, value, unit } });
+    }
+    /** Serialize with truncation. Returns { json, truncated, bytes }. */
+    serialize() {
+        let events = this.events;
+        let serialized = this.dump(events);
+        let truncated = false;
+        if (serialized.length > this.truncateBytes) {
+            // drop `data` on info events first, keep warn/error/metric payloads
+            events = events.map((e) => (e.level === 'info' && e.data !== undefined ? { ...e, data: undefined } : e));
+            serialized = this.dump(events);
+            truncated = true;
+        }
+        if (serialized.length > this.truncateBytes) {
+            // still too big: drop all `data`, keep errors + metrics + step names
+            events = events.map((e) => ({ ...e, data: undefined }));
+            serialized = this.dump(events);
+            truncated = true;
+        }
+        const warned = serialized.length > this.warnBytes;
+        return { json: serialized, truncated, bytes: serialized.length, warned };
+    }
+    async flush(store) {
+        const { json, truncated, bytes, warned } = this.serialize();
+        await store.write(this.runId, 'trace', 'trace', json, { mimeType: 'application/json', redactable: true });
+        return { bytes, truncated, warned };
+    }
+    getEvents() {
+        return this.events;
+    }
+    dump(events) {
+        return JSON.stringify({ runId: this.runId, version: '0.1', events }, null, 2);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/trace/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/trace/index.ts"],"names":[],"mappings":"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"}

package/dist/warnings.d.ts

@@ -0,0 +1,7 @@
+/** Warning constructors. Always use these so warning shape stays consistent. */
+import type { Warning, WarningSeverity } from './schema/index.js';
+export declare function warning(code: string, message: string, severity: WarningSeverity, targetId?: string): Warning;
+export declare const info: (code: string, message: string, targetId?: string) => Warning;
+export declare const warn: (code: string, message: string, targetId?: string) => Warning;
+export declare const errorw: (code: string, message: string, targetId?: string) => Warning;
+//# sourceMappingURL=warnings.d.ts.map

package/dist/warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAElE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAI5G;AAED,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,EAAE,WAAW,MAAM,KAAG,OAC9B,CAAC;AAE3C,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,EAAE,WAAW,MAAM,KAAG,OAC3B,CAAC;AAE9C,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,EAAE,WAAW,MAAM,KAAG,OAC/B,CAAC"}

package/dist/warnings.js

@@ -0,0 +1,10 @@
+export function warning(code, message, severity, targetId) {
+    const w = { code, message, severity };
+    if (targetId !== undefined)
+        w.targetId = targetId;
+    return w;
+}
+export const info = (code, message, targetId) => warning(code, message, 'info', targetId);
+export const warn = (code, message, targetId) => warning(code, message, 'warning', targetId);
+export const errorw = (code, message, targetId) => warning(code, message, 'error', targetId);
+//# sourceMappingURL=warnings.js.map

package/dist/warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.js","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,OAAe,EAAE,QAAyB,EAAE,QAAiB;IACjG,MAAM,CAAC,GAAY,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC/C,IAAI,QAAQ,KAAK,SAAS;QAAE,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAClD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,QAAiB,EAAW,EAAE,CAChF,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAE3C,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,QAAiB,EAAW,EAAE,CAChF,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAE9C,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,QAAiB,EAAW,EAAE,CAClF,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@visual-layer/core",
+  "version": "1.0.0",
+  "description": "ScreenGraph schema, contracts, artifact store, redaction, browser adapter",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/locotine/vision-layer.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b"
+  }
+}