@graview/core 0.1.0

package/dist/mutations/define-mutation.js

@@ -0,0 +1,181 @@
+import { GraphError } from "../graph/graph.js";
+import { TrackedReader } from "../graph/tracked.js";
+import { edgeId } from "../graph/types.js";
+export function defineMutation(name, spec) {
+    return { ...spec, name };
+}
+/** Whether an act takes the framework's `id` argument: it creates, and has no `id` of its own. */
+export function takesAnId(definition) {
+    if (!definition.creates?.length)
+        return false;
+    const shape = definition.input.shape;
+    return shape === undefined || !("id" in shape);
+}
+function requestedId(rawArgs) {
+    if (typeof rawArgs !== "object" || rawArgs === null)
+        return undefined;
+    const id = rawArgs["id"];
+    if (id === undefined)
+        return undefined;
+    if (typeof id !== "string" || id.trim().length === 0) {
+        throw new GraphError("An id must be a non-empty string", `Got ${JSON.stringify(id)}.`);
+    }
+    return id;
+}
+function withoutId(args) {
+    const { id: _id, ...rest } = args;
+    return rest;
+}
+/**
+ * An id from a name: the name's own letters, folded and hyphenated.
+ *
+ * It kept ASCII and dropped everything else, so "Zoë Lamarré" became
+ * `artist:zo-lamarr` — an address that is neither her name nor anybody's —
+ * and a name in any script without Latin letters became `item`. Accents are
+ * folded the way search folds them (`zoe-lamarre`, the id a person would
+ * guess), and a letter with no Latin form is kept as the letter it is.
+ */
+export function slug(label) {
+    return (label
+        .normalize("NFKD")
+        .replace(/\p{M}/gu, "")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, "-")
+        .replace(/^-+|-+$/g, "") || "item");
+}
+/**
+ * Runs a mutation against the graph WITHOUT applying it, returning the
+ * primitives it would emit plus the causal read set. Applying is the op
+ * log's job — keeping the two apart is what makes preview-as-diff free.
+ */
+export function compileMutation(graph, definition, rawArgs) {
+    /*
+     * THE ID A CALLER BROUGHT. An act that creates a kind takes an optional
+     * `id` the framework adds beside its own arguments (see `takesAnId`):
+     * lifted here, before the declaration's own schema parses the rest, so a
+     * strict input is not asked about an argument it never declared. It goes
+     * to the first node `freshId` mints, and an id already in the graph is a
+     * refusal — a seed being synced, or an agent that will name this node in
+     * its next call, needs exactly the id it asked for or an honest no.
+     */
+    const requested = takesAnId(definition) ? requestedId(rawArgs) : undefined;
+    const parsed = definition.input.safeParse(requested === undefined ? rawArgs : withoutId(rawArgs));
+    if (!parsed.success) {
+        throw new GraphError(`Invalid arguments for mutation "${definition.name}"`, parsed.error.issues
+            .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("; "));
+    }
+    const args = parsed.data;
+    const reader = new TrackedReader(graph);
+    const primitives = [];
+    const minted = new Set();
+    const context = {
+        graph: reader,
+        schema: graph.schema,
+        emit(primitive) {
+            primitives.push(primitive);
+        },
+        addNode(node) {
+            primitives.push({ op: "add-node", node });
+        },
+        removeNode(id) {
+            const node = reader.getNode(id);
+            if (!node)
+                throw new GraphError(`Cannot remove missing node "${id}"`);
+            const touching = new Map();
+            for (const edge of graph.outEdges(id))
+                touching.set(edgeId(edge), edge);
+            for (const edge of graph.inEdges(id))
+                touching.set(edgeId(edge), edge);
+            for (const edge of touching.values()) {
+                reader.getNode(edge.from);
+                reader.getNode(edge.to);
+                primitives.push({ op: "remove-edge", edge });
+            }
+            primitives.push({ op: "remove-node", node });
+        },
+        patchNode(id, fields) {
+            const node = reader.getNode(id);
+            if (!node)
+                throw new GraphError(`Cannot patch missing node "${id}"`);
+            const before = {};
+            const after = {};
+            for (const [key, value] of Object.entries(fields)) {
+                const current = node[key];
+                if (JSON.stringify(current) === JSON.stringify(value))
+                    continue;
+                before[key] = current;
+                after[key] = value;
+            }
+            if (Object.keys(after).length === 0)
+                return;
+            primitives.push({ op: "patch-node", id, before, after });
+        },
+        addEdge(edge) {
+            primitives.push({ op: "add-edge", edge });
+        },
+        removeEdge(edge) {
+            primitives.push({ op: "remove-edge", edge });
+        },
+        setSingleSource(kind, to, from) {
+            for (const edge of graph.inEdges(to, kind)) {
+                reader.getNode(edge.from);
+                if (edge.from === from)
+                    continue;
+                primitives.push({ op: "remove-edge", edge });
+            }
+            if (!graph.inEdges(to, kind).some((e) => e.from === from)) {
+                primitives.push({ op: "add-edge", edge: { kind, from, to } });
+            }
+        },
+        freshId(label, prefix) {
+            if (requested !== undefined && !minted.has(requested)) {
+                if (reader.has(requested)) {
+                    throw new GraphError(`Id "${requested}" is already taken`, `"${definition.name}" was asked to make a node with that id, and the graph has one. Pick another, or leave id out and let the act mint one.`);
+                }
+                minted.add(requested);
+                return requested;
+            }
+            const base = prefix ? `${prefix}:${slug(label)}` : slug(label);
+            if (!reader.has(base) && !minted.has(base)) {
+                minted.add(base);
+                return base;
+            }
+            let n = 2;
+            while (reader.has(`${base}-${n}`) || minted.has(`${base}-${n}`))
+                n++;
+            const id = `${base}-${n}`;
+            minted.add(id);
+            return id;
+        },
+    };
+    definition.apply(context, args);
+    const writes = new Set();
+    for (const primitive of primitives) {
+        switch (primitive.op) {
+            case "add-node":
+            case "remove-node":
+                writes.add(primitive.node.id);
+                break;
+            case "patch-node":
+                writes.add(primitive.id);
+                break;
+            case "add-edge":
+            case "remove-edge":
+                writes.add(primitive.edge.from);
+                writes.add(primitive.edge.to);
+                break;
+        }
+    }
+    const intent = definition.describe?.(args, reader) ??
+        `${definition.name}(${Object.entries(args)
+            .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+            .join(", ")})`;
+    return {
+        primitives,
+        reads: reader.reads(),
+        writes: [...writes],
+        intent,
+    };
+}
+//# sourceMappingURL=define-mutation.js.map

package/dist/mutations/define-mutation.js.map

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

package/dist/mutations/derive-edits.d.ts

@@ -0,0 +1,75 @@
+import type { AnySchema } from "../schema/schema.js";
+import type { AnyNodeDefinition } from "../schema/types.js";
+import type { AnyMutationDefinition } from "./types.js";
+/**
+ * A FIELD YOU COULD SET AT CREATION, YOU CAN CHANGE.
+ *
+ * Every app here had the same hole: a drill's minimum players asked for
+ * when the drill was made, shown on its card, and then frozen — no
+ * mutation took it, so the in-place edit honestly said "read-only" and
+ * there was nothing to reach for. The culture is right that every change
+ * is a named act, so the fix is not an anonymous `update`: it is a DERIVED,
+ * titled edit act per kind, covering exactly the settable fields nothing
+ * else writes, flowing through the policy like any named mutation. Opting
+ * out is a declaration (`fixed`, with the reason); and the checker warns
+ * when a field is still out of everyone's reach.
+ */
+/** The fields of a kind a person could change: declared, and not fixed. */
+export declare function settableFields(definition: AnyNodeDefinition): readonly string[];
+/** The kinds a mutation's subject accepts, resolved against the schema. */
+export declare function subjectKindsOf<S extends AnySchema>(schema: S, mutation: AnyMutationDefinition<S>): readonly string[];
+/**
+ * Which fields a mutation writes on a given subject kind: its declaration
+ * when it has one, the name-match guess when it does not.
+ */
+export declare function fieldsWrittenBy<S extends AnySchema>(mutation: AnyMutationDefinition<S>, definition: AnyNodeDefinition): readonly string[];
+/** kind → field → the declared mutations that write it. */
+export declare function fieldWriters<S extends AnySchema>(schema: S, mutations: readonly AnyMutationDefinition<S>[]): ReadonlyMap<string, ReadonlyMap<string, readonly string[]>>;
+/** The settable fields of a kind that no declared mutation writes. */
+export declare function unwrittenFields<S extends AnySchema>(schema: S, mutations: readonly AnyMutationDefinition<S>[], kind: string): readonly string[];
+/** The name the derived edit act for a kind carries. */
+export declare const editMutationName: (kind: string) => string;
+/**
+ * The declared acts a derived edit resolves its PERMISSION through: those
+ * that already write a field of the kind, and those that create it. Who may
+ * edit a drill is whoever the policy already lets change or make a drill —
+ * there is no second list.
+ */
+export declare function editVia<S extends AnySchema>(schema: S, mutations: readonly AnyMutationDefinition<S>[], kind: string): readonly string[];
+/**
+ * One edit act per kind that has something nobody else writes.
+ *
+ * Its input is the subject plus each uncovered field as an optional
+ * argument carrying the kind's OWN field schema, so validation is the
+ * declaration's; `writes` names those fields, so `editableFields` needs no
+ * guess. A kind whose every settable field is already written derives
+ * nothing, and an app that declares its own `edit-<kind>` keeps it.
+ */
+export declare function deriveEditMutations<S extends AnySchema>(schema: S, mutations: readonly AnyMutationDefinition<S>[]): AnyMutationDefinition<S>[];
+/** The name the derived remove act for a kind carries. */
+export declare const removeMutationName: (kind: string) => string;
+/**
+ * The declared acts a derived remove resolves its PERMISSION through: the
+ * ones that bring the kind into being. Who may make a plot may take one
+ * out — narrower than the edit's reading on purpose, because a role that
+ * may re-time a drill has not been trusted with losing it.
+ */
+export declare function removeVia<S extends AnySchema>(mutations: readonly AnyMutationDefinition<S>[], kind: string): readonly string[];
+/** The declared acts a derived act rides, whichever act it is. */
+export declare function derivedVia<S extends AnySchema>(schema: S, mutations: readonly AnyMutationDefinition<S>[], mutation: AnyMutationDefinition<S>): readonly string[] | undefined;
+/**
+ * WHAT WAS MADE CAN BE UNMADE.
+ *
+ * Every app had a way to add a task and, mostly, no way to lose one — so an
+ * agent redesigning a board, or a seed being brought in step with a live
+ * store, had nothing to call and rewrote the seed instead. The culture is
+ * right that every change is a named act, so the fix is a DERIVED, titled
+ * remove act per kind: destructive, so it ranks last and is marked; taking
+ * the node's edges with it, as `removeNode` does; logged and undoable like
+ * everything else; and permitted through the acts that create the kind.
+ * An app that declares its own `remove-<kind>` keeps it.
+ */
+export declare function deriveRemoveMutations<S extends AnySchema>(schema: S, mutations: readonly AnyMutationDefinition<S>[]): AnyMutationDefinition<S>[];
+/** Every act the framework derives for a declaration: the edits, then the removes. */
+export declare function deriveMutations<S extends AnySchema>(schema: S, mutations: readonly AnyMutationDefinition<S>[]): AnyMutationDefinition<S>[];
+//# sourceMappingURL=derive-edits.d.ts.map

package/dist/mutations/derive-edits.d.ts.map

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

package/dist/mutations/derive-edits.js

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import { labelOf } from "../schema/define-node.js";
+import { humaniseField, nounOf } from "../schema/define-node.js";
+import { nodeRef, nodeRefArgs } from "./node-ref.js";
+/**
+ * A FIELD YOU COULD SET AT CREATION, YOU CAN CHANGE.
+ *
+ * Every app here had the same hole: a drill's minimum players asked for
+ * when the drill was made, shown on its card, and then frozen — no
+ * mutation took it, so the in-place edit honestly said "read-only" and
+ * there was nothing to reach for. The culture is right that every change
+ * is a named act, so the fix is not an anonymous `update`: it is a DERIVED,
+ * titled edit act per kind, covering exactly the settable fields nothing
+ * else writes, flowing through the policy like any named mutation. Opting
+ * out is a declaration (`fixed`, with the reason); and the checker warns
+ * when a field is still out of everyone's reach.
+ */
+/** The fields of a kind a person could change: declared, and not fixed. */
+export function settableFields(definition) {
+    const shape = definition.fields.shape;
+    return Object.keys(shape).filter((field) => !(field in (definition.fixed ?? {})));
+}
+/** The kinds a mutation's subject accepts, resolved against the schema. */
+export function subjectKindsOf(schema, mutation) {
+    const subject = mutation.subject;
+    if (!subject)
+        return [];
+    return subject.kinds === "*"
+        ? schema.kinds
+        : subject.kinds;
+}
+/**
+ * Which fields a mutation writes on a given subject kind: its declaration
+ * when it has one, the name-match guess when it does not.
+ */
+export function fieldsWrittenBy(mutation, definition) {
+    const subject = mutation.subject;
+    if (!subject)
+        return [];
+    const declared = new Set(Object.keys(definition.fields.shape));
+    if (mutation.writes)
+        return mutation.writes.filter((field) => declared.has(field));
+    const shape = mutation.input.shape ?? {};
+    const refs = new Set(nodeRefArgs(mutation.input).map((ref) => ref.name));
+    return Object.keys(shape).filter((name) => name !== subject.arg && declared.has(name) && !refs.has(name));
+}
+/** kind → field → the declared mutations that write it. */
+export function fieldWriters(schema, mutations) {
+    const writers = new Map();
+    for (const mutation of mutations) {
+        for (const kind of subjectKindsOf(schema, mutation)) {
+            const definition = schema.tryDefinition(kind);
+            if (!definition)
+                continue;
+            for (const field of fieldsWrittenBy(mutation, definition)) {
+                const byField = writers.get(kind) ?? new Map();
+                byField.set(field, [...(byField.get(field) ?? []), mutation.name]);
+                writers.set(kind, byField);
+            }
+        }
+    }
+    return writers;
+}
+/** The settable fields of a kind that no declared mutation writes. */
+export function unwrittenFields(schema, mutations, kind) {
+    const definition = schema.tryDefinition(kind);
+    if (!definition)
+        return [];
+    const written = fieldWriters(schema, mutations).get(kind);
+    return settableFields(definition).filter((field) => !written?.has(field));
+}
+/** The name the derived edit act for a kind carries. */
+export const editMutationName = (kind) => `edit-${kind}`;
+/**
+ * The declared acts a derived edit resolves its PERMISSION through: those
+ * that already write a field of the kind, and those that create it. Who may
+ * edit a drill is whoever the policy already lets change or make a drill —
+ * there is no second list.
+ */
+export function editVia(schema, mutations, kind) {
+    const definition = schema.tryDefinition(kind);
+    if (!definition)
+        return [];
+    const via = new Set();
+    for (const mutation of mutations) {
+        if (mutation.derived)
+            continue;
+        if ((mutation.creates ?? []).includes(kind))
+            via.add(mutation.name);
+        if (subjectKindsOf(schema, mutation).includes(kind) &&
+            fieldsWrittenBy(mutation, definition).length > 0) {
+            via.add(mutation.name);
+        }
+    }
+    return [...via];
+}
+/**
+ * One edit act per kind that has something nobody else writes.
+ *
+ * Its input is the subject plus each uncovered field as an optional
+ * argument carrying the kind's OWN field schema, so validation is the
+ * declaration's; `writes` names those fields, so `editableFields` needs no
+ * guess. A kind whose every settable field is already written derives
+ * nothing, and an app that declares its own `edit-<kind>` keeps it.
+ */
+export function deriveEditMutations(schema, mutations) {
+    const taken = new Set(mutations.map((mutation) => mutation.name));
+    const derived = [];
+    for (const definition of schema.definitions) {
+        const kind = definition.kind;
+        const name = editMutationName(kind);
+        if (taken.has(name))
+            continue;
+        const fields = unwrittenFields(schema, mutations, kind);
+        if (fields.length === 0)
+            continue;
+        const shape = definition.fields.shape;
+        const noun = nounOf(definition, kind);
+        const said = fields.map((field) => humaniseField(field).toLowerCase());
+        derived.push({
+            name,
+            derived: { kind, act: "edit" },
+            title: `Change the ${noun}`,
+            description: `Change what was set when this ${noun} was made: ${said.join(", ")}.`,
+            subject: { kinds: [kind], arg: "id" },
+            writes: fields,
+            input: z.object({
+                id: nodeRef([kind]),
+                ...Object.fromEntries(fields.map((field) => [field, shape[field].optional()])),
+            }),
+            describe: (args, graph) => {
+                const node = graph.getNode(args.id);
+                const label = node ? labelOf(definition, node) : args.id;
+                /*
+                 * THE CHANGE AS THE RECORD READS IT. The log said "price → 49900"
+                 * and "condition → \"cpo\"" beside a card that says "Price $49,900"
+                 * and "Certified pre-owned": the declaration's own labels and
+                 * formats are the words, and the raw value only where there is none.
+                 */
+                const display = definition.display;
+                const quietly = (label) => (label === label.toUpperCase() ? label : label.charAt(0).toLowerCase() + label.slice(1));
+                const changes = fields
+                    .filter((field) => args[field] !== undefined)
+                    .map((field) => {
+                    const value = args[field];
+                    const format = display?.format?.[field];
+                    let said;
+                    try {
+                        said = format ? String(format(value)) : JSON.stringify(value);
+                    }
+                    catch {
+                        said = JSON.stringify(value);
+                    }
+                    return `${quietly(display?.labels?.[field] ?? humaniseField(field))} → ${said}`;
+                });
+                return `Change ${label}: ${changes.join(", ") || "nothing"}`;
+            },
+            apply(ctx, args) {
+                const patch = {};
+                for (const field of fields) {
+                    const value = args[field];
+                    if (value !== undefined)
+                        patch[field] = value;
+                }
+                if (Object.keys(patch).length === 0) {
+                    throw new Error(`Nothing to change — give at least one of ${said.join(", ")} a value.`);
+                }
+                ctx.patchNode(args.id, patch);
+            },
+        });
+    }
+    return derived;
+}
+/** The name the derived remove act for a kind carries. */
+export const removeMutationName = (kind) => `remove-${kind}`;
+/**
+ * The declared acts a derived remove resolves its PERMISSION through: the
+ * ones that bring the kind into being. Who may make a plot may take one
+ * out — narrower than the edit's reading on purpose, because a role that
+ * may re-time a drill has not been trusted with losing it.
+ */
+export function removeVia(mutations, kind) {
+    return mutations
+        .filter((mutation) => !mutation.derived && (mutation.creates ?? []).includes(kind))
+        .map((mutation) => mutation.name);
+}
+/** The declared acts a derived act rides, whichever act it is. */
+export function derivedVia(schema, mutations, mutation) {
+    if (!mutation.derived)
+        return undefined;
+    return mutation.derived.act === "edit"
+        ? editVia(schema, mutations, mutation.derived.kind)
+        : removeVia(mutations, mutation.derived.kind);
+}
+/**
+ * WHAT WAS MADE CAN BE UNMADE.
+ *
+ * Every app had a way to add a task and, mostly, no way to lose one — so an
+ * agent redesigning a board, or a seed being brought in step with a live
+ * store, had nothing to call and rewrote the seed instead. The culture is
+ * right that every change is a named act, so the fix is a DERIVED, titled
+ * remove act per kind: destructive, so it ranks last and is marked; taking
+ * the node's edges with it, as `removeNode` does; logged and undoable like
+ * everything else; and permitted through the acts that create the kind.
+ * An app that declares its own `remove-<kind>` keeps it.
+ */
+export function deriveRemoveMutations(schema, mutations) {
+    const taken = new Set(mutations.map((mutation) => mutation.name));
+    const derived = [];
+    for (const definition of schema.definitions) {
+        const kind = definition.kind;
+        const name = removeMutationName(kind);
+        if (taken.has(name))
+            continue;
+        const noun = nounOf(definition, kind);
+        derived.push({
+            name,
+            derived: { kind, act: "remove" },
+            title: `Remove the ${noun}`,
+            description: `Take this ${noun} out of the graph, with every tie it has. Undo puts it back.`,
+            subject: { kinds: [kind], arg: "id" },
+            destructive: true,
+            input: z.object({ id: nodeRef([kind]) }),
+            describe: (args, graph) => {
+                const id = args.id;
+                const node = graph.getNode(id);
+                return `Remove ${node ? labelOf(definition, node) : id}`;
+            },
+            apply(ctx, args) {
+                ctx.removeNode(args.id);
+            },
+        });
+    }
+    return derived;
+}
+/** Every act the framework derives for a declaration: the edits, then the removes. */
+export function deriveMutations(schema, mutations) {
+    return [...deriveEditMutations(schema, mutations), ...deriveRemoveMutations(schema, mutations)];
+}
+//# sourceMappingURL=derive-edits.js.map

package/dist/mutations/derive-edits.js.map

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

package/dist/mutations/form.d.ts

@@ -0,0 +1,63 @@
+import type { z } from "zod";
+/**
+ * A FORM, derived from a mutation's own input declaration.
+ *
+ * `argShape` answers "what sort of answer does one scalar argument want",
+ * which is enough for a prompt in the actions strip. A page is mostly forms,
+ * and a form needs the whole tree: a structured object is a fieldset, a
+ * discriminated union is a type picker followed by that type's fields, an
+ * array is a repeatable row. Until this existed, any mutation with a
+ * structured argument was honestly un-askable — the strip withheld it — and
+ * a routed page cannot withhold "New agreement": it has to render.
+ *
+ * Everything here is PLAIN DATA. A renderer (a page, the strip, an agent
+ * explaining itself) walks the tree; nothing downstream touches zod.
+ */
+export type FormField = ScalarField | {
+    readonly control: "node";
+    readonly name: string;
+    readonly optional: boolean;
+    readonly kinds: readonly string[];
+} | {
+    readonly control: "group";
+    readonly name: string;
+    readonly optional: boolean;
+    readonly fields: readonly FormField[];
+} | {
+    readonly control: "variant";
+    readonly name: string;
+    readonly optional: boolean;
+    /** The discriminating literal field shared by every option. */
+    readonly tag: string;
+    readonly options: readonly {
+        readonly value: string;
+        /** The option's remaining fields, the tag excluded. */
+        readonly fields: readonly FormField[];
+    }[];
+} | {
+    readonly control: "list";
+    readonly name: string;
+    readonly optional: boolean;
+    readonly item: FormField;
+} | {
+    readonly control: "opaque";
+    readonly name: string;
+    readonly optional: boolean;
+};
+export interface ScalarField {
+    readonly control: "text" | "date" | "number" | "choice" | "boolean";
+    readonly name: string;
+    readonly optional: boolean;
+    /** A date with a time of day in it (`YYYY-MM-DDTHH:MM`): asked for with a date AND a time. */
+    readonly time?: true;
+    readonly options?: readonly string[];
+    readonly min?: number;
+    readonly max?: number;
+}
+/** Describes one argument as a form control tree. */
+export declare function formField(name: string, schema: unknown): FormField;
+/** The whole form for a mutation input object, one field per argument. */
+export declare function formFields(input: z.ZodType | unknown): readonly FormField[];
+/** True when every control in the tree is renderable — nothing opaque. */
+export declare function formComplete(fields: readonly FormField[]): boolean;
+//# sourceMappingURL=form.d.ts.map

package/dist/mutations/form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.d.ts","sourceRoot":"","sources":["../../src/mutations/form.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GACjB,WAAW,GACX;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAClH;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,GACvH;IACE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS;QACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,uDAAuD;QACvD,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;KACvC,EAAE,CAAC;CACL,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GACzG;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AA6BD,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,CA+ElE;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,GAAG,SAAS,SAAS,EAAE,CAI3E;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAelE"}