@bestagentkits/render 0.1.0

package/dist/json.js

@@ -0,0 +1,47 @@
+/**
+ * JSON value model and canonical serialization.
+ *
+ * Canonical serialization is a determinism primitive: stable node IDs and
+ * determinism hashes are derived from it, so key order must not depend on how a
+ * document happened to be written.
+ */
+/** True for a plain object (not an array, not null). */
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** True for any JSON-serializable value. */
+export function isJsonValue(value) {
+    if (value === null)
+        return true;
+    const type = typeof value;
+    if (type === 'string' || type === 'boolean')
+        return true;
+    if (type === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (isPlainObject(value))
+        return Object.values(value).every(isJsonValue);
+    return false;
+}
+/**
+ * Serialize a JSON value with object keys sorted lexicographically.
+ *
+ * Used for content hashes, never for emitted HTML: emitted output uses the
+ * spec's own ordering where ordering is meaningful to a reader.
+ */
+export function canonicalStringify(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalStringify(item)).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+        return `{${entries
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalStringify(item)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,wDAAwD;AACxD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC;IAC1B,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAe,CAAC,CAAC;IAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAC1D,IAAI,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACzE,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAgB;IACjD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACxE,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAC7D,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACzC,CAAC;QACF,OAAO,IAAI,OAAO;aACf,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;aAC1E,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC"}

package/dist/registry/actions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The closed action vocabulary.
+ *
+ * A Page Spec can request behavior, never author it. There is no expression
+ * language, no selector language, and no handler body: an action is a record
+ * with a known `action` value and validated parameters. The runtime owns how
+ * each action is performed, including focus, keyboard, and ARIA updates.
+ */
+import { type DiagnosticBag } from '../diagnostics.js';
+import { type JsonValue } from '../json.js';
+import { type PropSchema, type PropValues } from './prop-schema.js';
+export type ActionType = 'copy' | 'open-url' | 'toggle' | 'set-value' | 'next' | 'previous' | 'select-tab' | 'expand' | 'collapse' | 'filter' | 'theme' | 'download';
+export interface ActionDefinition {
+    type: ActionType;
+    summary: string;
+    params: Record<string, PropSchema>;
+}
+/** Events a block may bind to. Anything else is a validation error. */
+export declare const ALLOWED_EVENTS: readonly ["click", "change", "input", "select", "filter", "open", "close"];
+export type ActionEvent = (typeof ALLOWED_EVENTS)[number];
+export declare const ACTION_DEFINITIONS: readonly ActionDefinition[];
+export declare function getAction(type: string): ActionDefinition | undefined;
+export declare function listActionTypes(): ActionType[];
+export interface ValidatedActions {
+    /** event name -> validated action records */
+    bindings: Record<string, PropValues[]>;
+}
+/**
+ * Validate an `on` binding map.
+ *
+ * Accepts either a single action object or a list of action objects per event.
+ * `path` points at the `on` key so diagnostics land on the author's input.
+ */
+export declare function validateActionMap(value: unknown, path: string, bag: DiagnosticBag): ValidatedActions;
+/** Validate a single action record against the closed vocabulary. */
+export declare function validateAction(value: unknown, path: string, bag: DiagnosticBag): PropValues | undefined;
+/** True when a string is a plain `state.` dotted key path. */
+export declare function isSafeStatePath(value: string): boolean;
+/** Collect every action record from a validated binding map. */
+export declare function bindingActions(bindings: Record<string, PropValues[]>): PropValues[];
+/** JSON-safe view of the vocabulary for `catalog()`. */
+export declare function actionsCatalog(): {
+    type: ActionType;
+    summary: string;
+}[];
+/** Exported for tests and docs: the raw `action` value of a binding. */
+export declare function actionTypeOf(action: JsonValue): string | undefined;
+//# sourceMappingURL=actions.d.ts.map

package/dist/registry/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/registry/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAW,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAEpG,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,UAAU,GACV,QAAQ,GACR,WAAW,GACX,MAAM,GACN,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,OAAO,GACP,UAAU,CAAC;AAEf,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC;AAgBD,uEAAuE;AACvE,eAAO,MAAM,cAAc,4EAQjB,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EA0GzD,CAAC;AAIF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAEpE;AAED,wBAAgB,eAAe,IAAI,UAAU,EAAE,CAE9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,aAAa,GACjB,gBAAgB,CAqClB;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,aAAa,GACjB,UAAU,GAAG,SAAS,CA+DxB;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,GAAG,UAAU,EAAE,CAEnF;AAED,wDAAwD;AACxD,wBAAgB,cAAc,IAAI;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAKxE;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAIlE"}

package/dist/registry/actions.js

@@ -0,0 +1,274 @@
+/**
+ * The closed action vocabulary.
+ *
+ * A Page Spec can request behavior, never author it. There is no expression
+ * language, no selector language, and no handler body: an action is a record
+ * with a known `action` value and validated parameters. The runtime owns how
+ * each action is performed, including focus, keyboard, and ARIA updates.
+ */
+import { pathKey } from '../diagnostics.js';
+import { isPlainObject } from '../json.js';
+import { NODE_ID_PATTERN, validateProps } from './prop-schema.js';
+const idRef = (description) => ({
+    kind: 'string',
+    id: true,
+    required: true,
+    description,
+});
+const statePath = {
+    kind: 'string',
+    required: true,
+    maxLength: 128,
+    description: 'State path of the form `state.<key>[.<key>...]`.',
+};
+/** Events a block may bind to. Anything else is a validation error. */
+export const ALLOWED_EVENTS = [
+    'click',
+    'change',
+    'input',
+    'select',
+    'filter',
+    'open',
+    'close',
+];
+export const ACTION_DEFINITIONS = [
+    {
+        type: 'copy',
+        summary: 'Copy the text content of the target node to the clipboard.',
+        params: { target: idRef('Node whose text is copied.') },
+    },
+    {
+        type: 'open-url',
+        summary: 'Open an allowlisted URL in a new tab.',
+        params: {
+            url: { kind: 'url', required: true, description: 'Destination URL.' },
+            label: { kind: 'string', maxLength: 120, description: 'Accessible label for the link.' },
+        },
+    },
+    {
+        type: 'toggle',
+        summary: 'Toggle the expanded, open, or active state of the target node.',
+        params: { target: idRef('Node to toggle.') },
+    },
+    {
+        type: 'set-value',
+        summary: 'Set a page state value without an expression.',
+        params: {
+            path: statePath,
+            value: {
+                kind: 'json',
+                description: 'Literal value assigned to the state path.',
+                maxBytes: 4_096,
+            },
+        },
+    },
+    {
+        type: 'next',
+        summary: 'Advance a carousel, slideshow, or step sequence to the next item.',
+        params: { target: { kind: 'string', id: true, description: 'Block to advance.' } },
+    },
+    {
+        type: 'previous',
+        summary: 'Move a carousel, slideshow, or step sequence to the previous item.',
+        params: { target: { kind: 'string', id: true, description: 'Block to rewind.' } },
+    },
+    {
+        type: 'select-tab',
+        summary: 'Select a tab by index or id inside a tabs block.',
+        params: {
+            target: idRef('Tabs block to update.'),
+            index: {
+                kind: 'number',
+                integer: true,
+                min: 0,
+                max: 200,
+                description: 'Zero-based tab index.',
+            },
+            tabId: { kind: 'string', id: true, description: 'Tab id, as an alternative to index.' },
+        },
+    },
+    {
+        type: 'expand',
+        summary: 'Expand a disclosure or accordion section.',
+        params: { target: idRef('Section to expand.') },
+    },
+    {
+        type: 'collapse',
+        summary: 'Collapse a disclosure or accordion section.',
+        params: { target: idRef('Section to collapse.') },
+    },
+    {
+        type: 'filter',
+        summary: 'Filter a collection by the current search input value.',
+        params: {
+            target: idRef('Collection to filter.'),
+            match: {
+                kind: 'string',
+                enum: ['text', 'label', 'value'],
+                description: 'Which part of each item is matched.',
+            },
+            query: {
+                kind: 'string',
+                maxLength: 200,
+                description: 'Static query when no input is bound.',
+            },
+        },
+    },
+    {
+        type: 'theme',
+        summary: 'Switch the page theme.',
+        params: {
+            value: {
+                kind: 'string',
+                enum: ['toggle', 'light', 'dark', 'system'],
+                description: 'Target theme, or `toggle` to flip the current one.',
+            },
+        },
+    },
+    {
+        type: 'download',
+        summary: 'Download the target node content as a file.',
+        params: {
+            target: idRef('Node whose text is downloaded.'),
+            filename: {
+                kind: 'string',
+                maxLength: 120,
+                description: 'Suggested filename; sanitized before use.',
+            },
+        },
+    },
+];
+const BY_TYPE = new Map(ACTION_DEFINITIONS.map((definition) => [definition.type, definition]));
+export function getAction(type) {
+    return BY_TYPE.get(type);
+}
+export function listActionTypes() {
+    return ACTION_DEFINITIONS.map((definition) => definition.type);
+}
+/**
+ * Validate an `on` binding map.
+ *
+ * Accepts either a single action object or a list of action objects per event.
+ * `path` points at the `on` key so diagnostics land on the author's input.
+ */
+export function validateActionMap(value, path, bag) {
+    const bindings = {};
+    if (value === undefined)
+        return { bindings };
+    if (!isPlainObject(value)) {
+        bag.add({ code: 'SPEC_VALIDATION_ERROR', path, message: 'expected an event map object' });
+        return { bindings };
+    }
+    for (const [event, binding] of Object.entries(value)) {
+        const eventPath = pathKey(path, event);
+        if (!ALLOWED_EVENTS.includes(event)) {
+            bag.add({
+                code: 'SPEC_VALIDATION_ERROR',
+                path: eventPath,
+                message: `unknown event "${event}"`,
+                details: { allowed: [...ALLOWED_EVENTS] },
+            });
+            continue;
+        }
+        const candidates = Array.isArray(binding) ? binding : [binding];
+        if (candidates.length > 8) {
+            bag.add({
+                code: 'SPEC_BOUNDS_ERROR',
+                path: eventPath,
+                message: `event binds ${candidates.length} actions, limit is 8`,
+            });
+            continue;
+        }
+        const validated = [];
+        for (let index = 0; index < candidates.length; index += 1) {
+            const candidatePath = Array.isArray(binding) ? `${eventPath}[${index}]` : eventPath;
+            const action = validateAction(candidates[index], candidatePath, bag);
+            if (action !== undefined)
+                validated.push(action);
+        }
+        if (validated.length > 0)
+            bindings[event] = validated;
+    }
+    return { bindings };
+}
+/** Validate a single action record against the closed vocabulary. */
+export function validateAction(value, path, bag) {
+    if (!isPlainObject(value)) {
+        bag.add({ code: 'SPEC_VALIDATION_ERROR', path, message: 'expected an action object' });
+        return undefined;
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== 'action' && /^on[A-Z]/.test(key)) {
+            bag.add({
+                code: 'POLICY_VIOLATION',
+                path: pathKey(path, key),
+                message: 'inline event-handler source is not accepted',
+            });
+        }
+    }
+    const actionType = value.action;
+    if (typeof actionType !== 'string') {
+        bag.add({
+            code: 'SPEC_VALIDATION_ERROR',
+            path: pathKey(path, 'action'),
+            message: 'action requires an "action" key',
+        });
+        return undefined;
+    }
+    const definition = BY_TYPE.get(actionType);
+    if (definition === undefined) {
+        bag.add({
+            code: 'SPEC_VALIDATION_ERROR',
+            path: pathKey(path, 'action'),
+            message: `unknown action "${actionType}"`,
+            details: { allowed: listActionTypes() },
+        });
+        return undefined;
+    }
+    const { action: _ignored, ...rest } = value;
+    const params = validateProps(definition.params, rest, path, bag);
+    // A state path is the only dynamic indirection allowed, and it is a plain
+    // dotted key path — never an expression.
+    const statePathValue = params.path;
+    if (typeof statePathValue === 'string' && !isSafeStatePath(statePathValue)) {
+        bag.add({
+            code: 'POLICY_VIOLATION',
+            path: pathKey(path, 'path'),
+            message: `"${statePathValue}" is not a state path of the form state.<key>[.<key>...]`,
+        });
+        return undefined;
+    }
+    const target = params.target;
+    if (typeof target === 'string' && !NODE_ID_PATTERN.test(target)) {
+        bag.add({
+            code: 'SPEC_VALIDATION_ERROR',
+            path: pathKey(path, 'target'),
+            message: `"${target}" is not a valid node id`,
+        });
+        return undefined;
+    }
+    return { action: actionType, ...params };
+}
+/** True when a string is a plain `state.` dotted key path. */
+export function isSafeStatePath(value) {
+    return /^state\.[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/.test(value);
+}
+/** Collect every action record from a validated binding map. */
+export function bindingActions(bindings) {
+    return Object.values(bindings).flat();
+}
+/** JSON-safe view of the vocabulary for `catalog()`. */
+export function actionsCatalog() {
+    return ACTION_DEFINITIONS.map((definition) => ({
+        type: definition.type,
+        summary: definition.summary,
+    }));
+}
+/** Exported for tests and docs: the raw `action` value of a binding. */
+export function actionTypeOf(action) {
+    if (!isPlainObject(action))
+        return undefined;
+    const value = action.action;
+    return typeof value === 'string' ? value : undefined;
+}
+//# sourceMappingURL=actions.js.map

package/dist/registry/actions.js.map

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

package/dist/registry/prop-schema.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Declarative property schemas.
+ *
+ * One source of truth serves three consumers: runtime validation (with stable
+ * JSON paths), the published JSON Schema, and the compact `catalog()` /
+ * `describe()` contracts. Keeping them derived from one definition is what
+ * stops the documentation from drifting away from the validator.
+ */
+import { DiagnosticBag } from '../diagnostics.js';
+import { type JsonValue } from '../json.js';
+export type PropSchema = StringPropSchema | TextPropSchema | NumberPropSchema | BooleanPropSchema | UrlPropSchema | ListPropSchema | ObjectPropSchema | RecordPropSchema | OneOfPropSchema | JsonPropSchema;
+interface PropSchemaBase {
+    /** Reject the document when the property is absent. */
+    required?: boolean;
+    description?: string;
+}
+export interface StringPropSchema extends PropSchemaBase {
+    kind: 'string';
+    default?: string;
+    enum?: readonly string[];
+    maxLength?: number;
+    /** Validate as a node-safe identifier (`^[a-z0-9][a-z0-9-]{0,63}$`). */
+    id?: boolean;
+}
+/** Long-form single-line or multi-line text. Escaped at emission. */
+export interface TextPropSchema extends PropSchemaBase {
+    kind: 'text';
+    default?: string;
+    maxLength?: number;
+}
+export interface NumberPropSchema extends PropSchemaBase {
+    kind: 'number';
+    default?: number;
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}
+export interface BooleanPropSchema extends PropSchemaBase {
+    kind: 'boolean';
+    default?: boolean;
+}
+/**
+ * A link or asset reference. A relative path stays local; an absolute URL must
+ * use an allowlisted scheme. `data:` and `javascript:` are never accepted.
+ */
+export interface UrlPropSchema extends PropSchemaBase {
+    kind: 'url';
+    default?: string;
+    schemes?: readonly string[];
+}
+export interface ListPropSchema extends PropSchemaBase {
+    kind: 'list';
+    of: PropSchema;
+    minItems?: number;
+    maxItems?: number;
+}
+export interface ObjectPropSchema extends PropSchemaBase {
+    kind: 'object';
+    fields: Record<string, PropSchema>;
+}
+/** An open-keyed map, e.g. `state` or key/value lists. */
+export interface RecordPropSchema extends PropSchemaBase {
+    kind: 'record';
+    of: PropSchema;
+    maxKeys?: number;
+}
+export interface OneOfPropSchema extends PropSchemaBase {
+    kind: 'oneOf';
+    options: readonly PropSchema[];
+}
+/**
+ * A bounded, structurally-opaque JSON value validated by a capability adapter
+ * (for example an `ak:diagram` typed IR payload). It is still size-bounded and
+ * still scanned for forbidden keys.
+ */
+export interface JsonPropSchema extends PropSchemaBase {
+    kind: 'json';
+    description: string;
+    maxBytes?: number;
+    /** JSON Schema `$ref` used when projecting this prop into the spec schema. */
+    schemaRef?: string;
+}
+export declare const DEFAULT_URL_SCHEMES: readonly ["https", "http", "mailto"];
+export declare const NODE_ID_PATTERN: RegExp;
+export type PropValues = Record<string, JsonValue>;
+export interface PropValidationResult {
+    /** Validated values with defaults applied, in schema key order. */
+    values: PropValues;
+    /** Node-safe author IDs discovered in this subtree, mapped to their paths. */
+    authorIds: {
+        id: string;
+        path: string;
+    }[];
+}
+/**
+ * Validate one property value against its schema, appending diagnostics and
+ * returning the normalized value (or `undefined` when absent/optional).
+ */
+export declare function validateProp(schema: PropSchema, value: unknown, path: string, bag: DiagnosticBag): JsonValue | undefined;
+/**
+ * Validate a props object against a block's property schema. Unknown keys are
+ * errors: a silently ignored prop is a silent authoring mistake.
+ */
+export declare function validateProps(fields: Record<string, PropSchema>, value: unknown, path: string, bag: DiagnosticBag): PropValues;
+/** Project a prop schema into JSON Schema for the published spec contract. */
+export declare function propSchemaToJsonSchema(schema: PropSchema): Record<string, unknown>;
+export {};
+//# sourceMappingURL=prop-schema.d.ts.map

package/dist/registry/prop-schema.d.ts.map

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