@fluixi/devtools 0.2.0-alpha.1 → 0.2.0-alpha.3

package/dist/palette.d.ts

@@ -0,0 +1,11 @@
+import type { NodeKind } from './instrument.js';
+/** Element rows exist only in the tree, which is why this is wider than NodeKind. */
+export type ColouredKind = NodeKind | 'element';
+export declare const KIND_COLOR: Record<ColouredKind, string>;
+/** The variable a host can set to override one, per kind. */
+export declare const kindVar: (kind: ColouredKind) => string;
+/** `var(--fx-kind-memo, #a78bfa)`, so a host may theme it and nothing breaks if it does not. */
+export declare const kindColor: (kind: ColouredKind) => string;
+/** One rule per kind, built from the table so a new kind cannot be missed in one host. */
+export declare function kindRules(selector: (kind: ColouredKind) => string, property: string): string;
+//# sourceMappingURL=palette.d.ts.map

package/dist/palette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"palette.d.ts","sourceRoot":"","sources":["../src/palette.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,qFAAqF;AACrF,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAiBnD,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,OAAO,GAAI,MAAM,YAAY,KAAG,MAA6B,CAAC;AAE3E,gGAAgG;AAChG,eAAO,MAAM,SAAS,GAAI,MAAM,YAAY,KAAG,MACD,CAAC;AAI/C,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5F"}

package/dist/palette.js

@@ -0,0 +1,27 @@
+export const KIND_COLOR = {
+    state: '#34d399',
+    memo: '#a78bfa',
+    effect: '#fbbf24',
+    store: '#38bdf8',
+    resource: '#fb7185',
+    component: '#f0abfc',
+    provider: '#fb923c',
+    control: '#22d3ee',
+    router: '#818cf8',
+    handler: '#f472b6',
+    context: '#a3e635',
+    directive: '#5eead4',
+    binding: '#5eead4',
+    setter: '#fb7185',
+    group: '#8a90a2',
+    element: '#8a90a2',
+};
+/** The variable a host can set to override one, per kind. */
+export const kindVar = (kind) => `--fx-kind-${kind}`;
+/** `var(--fx-kind-memo, #a78bfa)`, so a host may theme it and nothing breaks if it does not. */
+export const kindColor = (kind) => `var(${kindVar(kind)}, ${KIND_COLOR[kind]})`;
+const KINDS = Object.keys(KIND_COLOR);
+/** One rule per kind, built from the table so a new kind cannot be missed in one host. */
+export function kindRules(selector, property) {
+    return KINDS.map((kind) => `${selector(kind)} { ${property}: ${kindColor(kind)}; }`).join('\n');
+}

package/dist/path.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Showing a file path at the length a reader wants.
+ *
+ * A node the framework made carries the path of the file that made it, on the machine that
+ * ran it: `/Users/someone/work/app/packages/dom/src/lib/dom/runtime.ts`. All of it before
+ * the package name says nothing about the project, and it is most of the line.
+ *
+ * The full path is kept for opening the file — only what is displayed is shortened.
+ */
+/**
+ * The part of `file` worth showing.
+ *
+ * Tried in order: below the project root when the host knows it, then the package a
+ * node_modules path names, then the workspace package a monorepo path names. A path that
+ * matches none of those is left as it is — guessing at a shorter form would hide which file
+ * it is, and the point of the line is to say that.
+ */
+export declare function shortenPath(file: string, root?: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAyB/D"}

package/dist/path.js

@@ -0,0 +1,49 @@
+/**
+ * Showing a file path at the length a reader wants.
+ *
+ * A node the framework made carries the path of the file that made it, on the machine that
+ * ran it: `/Users/someone/work/app/packages/dom/src/lib/dom/runtime.ts`. All of it before
+ * the package name says nothing about the project, and it is most of the line.
+ *
+ * The full path is kept for opening the file — only what is displayed is shortened.
+ */
+/** Windows separators, and the leading slash an origin-stripped path can lose. */
+const normalize = (file) => file.replace(/\\/g, '/');
+/** `Users/…`, `home/…`: an absolute path whose leading slash was trimmed off. */
+const ROOTED = /^\/|^(Users|home|var|opt|private|tmp|mnt|srv)\//;
+/** Where a monorepo keeps the things it builds. */
+const WORKSPACE_DIRS = new Set(['packages', 'apps', 'libs', 'examples']);
+/**
+ * The part of `file` worth showing.
+ *
+ * Tried in order: below the project root when the host knows it, then the package a
+ * node_modules path names, then the workspace package a monorepo path names. A path that
+ * matches none of those is left as it is — guessing at a shorter form would hide which file
+ * it is, and the point of the line is to say that.
+ */
+export function shortenPath(file, root) {
+    const path = normalize(file);
+    if (root) {
+        const base = normalize(root).replace(/\/+$/, '');
+        if (base && path.startsWith(`${base}/`))
+            return path.slice(base.length + 1);
+        // The path lost its leading slash on the way here; the root still has one.
+        if (base.startsWith('/') && path.startsWith(`${base.slice(1)}/`))
+            return path.slice(base.length);
+    }
+    // Everything up to the last node_modules is the machine's, not the project's.
+    const installed = path.lastIndexOf('node_modules/');
+    if (installed >= 0)
+        return path.slice(installed + 'node_modules/'.length);
+    // A monorepo package, which is where a framework's own files sit while it is worked on.
+    // The last of these wins: a checkout under `~/Developer/libs` has one in the machine's
+    // part of the path as well as the project's, and the project's is the one meant.
+    if (ROOTED.test(path)) {
+        const segments = path.split('/');
+        for (let i = segments.length - 2; i > 0; i--) {
+            if (WORKSPACE_DIRS.has(segments[i]))
+                return segments.slice(i).join('/');
+        }
+    }
+    return path;
+}

package/dist/plugin.d.ts

@@ -0,0 +1,121 @@
+import type { NodeKind, RNode } from './instrument.js';
+/** A directive the runtime applied to an element. */
+export interface DirectiveReport {
+    /** The node it was applied inside, usually a component. */
+    owner: number | undefined;
+    /** `use`, `class`, `style`, `bind`. */
+    kind: string;
+    /** The key after the colon, or the function name for `use:`. */
+    name: string;
+    /** The element as a selector. */
+    element: string;
+    /** The element itself. Only in the page, and the key to annotate it by. */
+    target?: unknown;
+    at?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    };
+}
+/** A node a plugin contributes. Ids come from the graph so they cannot collide. */
+export interface PluginNode {
+    label: string;
+    kind: NodeKind;
+    createdIn?: number;
+    deps?: number[];
+    /** Short enough for a card. */
+    value?: string;
+    /** The whole of it, for the inspector. */
+    detail?: string;
+    /**
+     * Whether the application wrote this or the framework did. False folds it into the
+     * machinery card, the way an unnamed memo is folded.
+     */
+    authored?: boolean;
+    source?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    };
+}
+/** A context provided or read. */
+export interface ContextReport {
+    /** The node it happened in. */
+    owner: number | undefined;
+    /** Identity of the context, stable for its lifetime. */
+    id: symbol;
+    /** What the symbol was created with, when it says anything. */
+    name: string;
+    /** Label of the node it happened in, for naming a context nobody named. */
+    ownerLabel?: string;
+    /** Where the context was written, and whether that was inside a package. */
+    at?: {
+        file?: string;
+        line?: number;
+        column?: number;
+        external?: boolean;
+    };
+    kind: 'provide' | 'read';
+    /** Formatted, since a panel elsewhere cannot hold the value itself. Not yet clipped. */
+    value?: string;
+}
+/** What a plugin gets in the page. */
+export interface CollectContext {
+    onDirective(fn: (report: DirectiveReport) => void): void;
+    onContext(fn: (report: ContextReport) => void): void;
+    /** Attach data under this plugin's name. Must survive JSON.stringify. */
+    annotate(id: number, data: unknown): void;
+    /**
+     * The same, for an element rather than a node. A directive belongs to the element it was
+     * applied to, and an element is not a node, so it is keyed by the element itself and
+     * lands on the description a panel draws.
+     */
+    annotateElement(target: unknown, data: unknown): void;
+    /** What this plugin already attached to an element. */
+    elementAnnotation(target: unknown): unknown;
+    add(node: PluginNode): number;
+    /**
+     * Say what a plain component really is. A component that exists to provide a context is a
+     * provider, and nothing but the plugin watching the context can know that.
+     *
+     * Ignored for a node the framework already named, and ignored for any kind that is not
+     * itself a tag: a Router that provides a context is still a Router, and a component
+     * relabelled a signal would leave the tree along with everything it rendered.
+     */
+    retype(id: number, kind: NodeKind): void;
+    /** What this plugin already attached, for adding to it rather than replacing it. */
+    annotation(id: number): unknown;
+}
+/** A line a plugin adds to the inspector. `at` makes it a link the host can open. */
+export interface PluginRow {
+    label: string;
+    value?: string;
+    at?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    };
+}
+export interface DevtoolsPlugin {
+    /** Namespaces everything it writes. */
+    name: string;
+    /** In the page. */
+    collect?(ctx: CollectContext): void;
+    /** In a panel, for the selected node. Sees only what crossed the wire. */
+    rows?(node: RNode, graph: Map<number, RNode>): PluginRow[];
+    /** A short word next to the label, in the tree and on the card. */
+    badge?(node: RNode): string | undefined;
+    /** The same, for an element row. Given what plugins attached to that element. */
+    elementBadge?(extra: Record<string, unknown>): string | undefined;
+    /** Rows for a selected element row. */
+    elementRows?(extra: Record<string, unknown>): PluginRow[];
+}
+/** Replaced rather than added twice, so a module evaluated in two bundles does not double. */
+export declare function registerDevtoolsPlugin(plugin: DevtoolsPlugin): void;
+export declare function devtoolsPlugins(): readonly DevtoolsPlugin[];
+export declare function annotationOf(node: RNode, name: string): unknown;
+export declare function pluginRows(node: RNode, graph: Map<number, RNode>): PluginRow[];
+export declare function pluginElementRows(extra?: Record<string, unknown>): PluginRow[];
+export declare function pluginElementBadge(extra?: Record<string, unknown>): string | undefined;
+export declare function pluginBadge(node: RNode): string | undefined;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -0,0 +1,74 @@
+const plugins = [];
+/** Replaced rather than added twice, so a module evaluated in two bundles does not double. */
+export function registerDevtoolsPlugin(plugin) {
+    const at = plugins.findIndex((p) => p.name === plugin.name);
+    if (at === -1)
+        plugins.push(plugin);
+    else
+        plugins[at] = plugin;
+}
+export function devtoolsPlugins() {
+    return plugins;
+}
+export function annotationOf(node, name) {
+    return node.extra?.[name];
+}
+export function pluginRows(node, graph) {
+    const out = [];
+    for (const plugin of plugins) {
+        if (!plugin.rows)
+            continue;
+        // A plugin with a bug is not a reason for the panel to stop.
+        try {
+            out.push(...plugin.rows(node, graph));
+        }
+        catch {
+            /* ignored */
+        }
+    }
+    return out;
+}
+export function pluginElementRows(extra) {
+    if (!extra)
+        return [];
+    const out = [];
+    for (const plugin of plugins) {
+        if (!plugin.elementRows)
+            continue;
+        try {
+            out.push(...plugin.elementRows(extra));
+        }
+        catch {
+            /* ignored */
+        }
+    }
+    return out;
+}
+export function pluginElementBadge(extra) {
+    if (!extra)
+        return undefined;
+    for (const plugin of plugins) {
+        try {
+            const badge = plugin.elementBadge?.(extra);
+            if (badge)
+                return badge;
+        }
+        catch {
+            /* ignored */
+        }
+    }
+    return undefined;
+}
+export function pluginBadge(node) {
+    for (const plugin of plugins) {
+        try {
+            const badge = plugin.badge?.(node);
+            if (badge)
+                return badge;
+        }
+        catch {
+            /* ignored */
+        }
+    }
+    return undefined;
+}

package/dist/plugins/context.d.ts

@@ -0,0 +1,10 @@
+import { type DevtoolsPlugin } from '../plugin.js';
+export declare const NAME = "context";
+/** What lands on a component under this plugin's name. */
+export interface ContextNote {
+    name: string;
+    kind: 'provide' | 'read';
+    value?: string;
+}
+export declare const contextPlugin: DevtoolsPlugin;
+//# sourceMappingURL=context.d.ts.map

package/dist/plugins/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/plugins/context.ts"],"names":[],"mappings":"AAKA,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAI3E,eAAO,MAAM,IAAI,YAAY,CAAC;AAE9B,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,aAAa,EAAE,cAuE3B,CAAC"}

package/dist/plugins/context.js

@@ -0,0 +1,80 @@
+// Which components provide a context, and which read it.
+//
+// The graph cannot show this on its own. A provider stamps a value on the owner chain and a
+// reader walks up looking for it, so neither is a dependency and no edge is ever made. The
+// two components end up as unrelated cards even though one feeds the other.
+import { registerDevtoolsPlugin } from '../plugin.js';
+import { shorten } from '../format.js';
+export const NAME = 'context';
+export const contextPlugin = {
+    name: NAME,
+    collect(ctx) {
+        /** One node per context, however many components touch it. */
+        const nodes = new Map();
+        ctx.onContext((report) => {
+            if (report.owner === undefined)
+                return;
+            let node = nodes.get(report.id);
+            if (node === undefined) {
+                // `createContext` names its symbol `context` unless told otherwise, so an unnamed
+                // one is said by where it came from rather than drawn seven times identically.
+                const label = report.name === 'context' && report.ownerLabel
+                    ? `${report.ownerLabel} context`
+                    : report.name;
+                node = ctx.add({
+                    label,
+                    kind: 'context',
+                    // A context is created at module scope with nothing running, so the only line it
+                    // can carry is the one that provided or read it.
+                    ...(report.at ? { source: report.at } : {}),
+                    // The router's own contexts are the framework's, and belong in its card rather
+                    // than beside the ones the application wrote.
+                    authored: report.at?.external !== true,
+                    // Under whoever provided it. A context read with no provider above it belongs to
+                    // the reader, which is the honest place for a default value.
+                    createdIn: report.owner,
+                    // Short on the card, whole in the inspector, the way every other node works.
+                    ...(report.value !== undefined
+                        ? { value: shorten(report.value), detail: report.value }
+                        : {}),
+                });
+                nodes.set(report.id, node);
+            }
+            // A component that provides is a provider. Only this plugin can tell, and a card
+            // reading `component` says nothing about why it is there.
+            if (report.kind === 'provide')
+                ctx.retype(report.owner, 'provider');
+            const held = ctx.annotation(report.owner) ?? [];
+            const already = held.some((n) => n.name === report.name && n.kind === report.kind);
+            if (already)
+                return;
+            held.push({
+                name: report.name,
+                kind: report.kind,
+                ...(report.value !== undefined ? { value: report.value } : {}),
+            });
+            ctx.annotate(report.owner, held);
+        });
+    },
+    rows(node) {
+        const notes = node.extra?.[NAME];
+        if (!notes?.length)
+            return [];
+        return notes.map((note) => ({
+            label: note.kind === 'provide' ? `provides ${note.name}` : `reads ${note.name}`,
+            ...(note.value !== undefined ? { value: note.value } : {}),
+        }));
+    },
+    badge(node) {
+        const notes = node.extra?.[NAME];
+        if (!notes?.length)
+            return undefined;
+        const given = notes.filter((n) => n.kind === 'provide');
+        if (given.length === 1)
+            return `provides ${given[0].name}`;
+        if (given.length > 1)
+            return `provides ${given.length}`;
+        return notes.length === 1 ? `reads ${notes[0].name}` : `reads ${notes.length}`;
+    },
+};
+registerDevtoolsPlugin(contextPlugin);

package/dist/plugins/directives.d.ts

@@ -0,0 +1,25 @@
+import { type DevtoolsPlugin } from '../plugin.js';
+export declare const NAME = "directives";
+/** The notes on an element of a description, for a panel drawing element rows. */
+export declare function directivesOn(extra?: Record<string, unknown>): DirectiveNote[];
+/** A short word for a badge. The whole expression an inline ref was written as is not one. */
+export declare function directiveBadge(notes: DirectiveNote[]): string | undefined;
+/** A row per directive, for the inspector. */
+export declare function directiveRows(notes: DirectiveNote[]): {
+    label: string;
+    value?: string;
+    at?: DirectiveNote['at'];
+}[];
+/** What lands on a node under this plugin's name. */
+export interface DirectiveNote {
+    kind: string;
+    name: string;
+    element: string;
+    at?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    };
+}
+export declare const directivesPlugin: DevtoolsPlugin;
+//# sourceMappingURL=directives.d.ts.map

package/dist/plugins/directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../../src/plugins/directives.ts"],"names":[],"mappings":"AAKA,OAAO,EAA0B,KAAK,cAAc,EAAwB,MAAM,cAAc,CAAC;AAGjG,eAAO,MAAM,IAAI,eAAe,CAAC;AAEjC,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,EAAE,CAE7E;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,GAAG,SAAS,CAKzE;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAA;CAAE,EAAE,CAMnH;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAKD,eAAO,MAAM,gBAAgB,EAAE,cAiD9B,CAAC"}

package/dist/plugins/directives.js

@@ -0,0 +1,78 @@
+// What directives an element was given.
+//
+// The graph already shows that something writes a class or a style, because the dom reports
+// the binding. It does not show which directive asked for it, and `use:` is invisible
+// entirely since a custom directive is a function call with no reactive node behind it.
+import { registerDevtoolsPlugin } from '../plugin.js';
+export const NAME = 'directives';
+/** The notes on an element of a description, for a panel drawing element rows. */
+export function directivesOn(extra) {
+    return extra?.[NAME] ?? [];
+}
+/** A short word for a badge. The whole expression an inline ref was written as is not one. */
+export function directiveBadge(notes) {
+    if (!notes.length)
+        return undefined;
+    const first = notes[0];
+    const short = first.kind === 'ref' ? 'ref' : label(first);
+    return notes.length > 1 ? `${short} +${notes.length - 1}` : short;
+}
+/** A row per directive, for the inspector. */
+export function directiveRows(notes) {
+    return notes.map((note) => ({
+        label: label(note),
+        value: note.element,
+        ...(note.at ? { at: note.at } : {}),
+    }));
+}
+const label = (note) => note.kind === 'ref' ? `ref ${note.name}` : `${note.kind}:${note.name}`;
+export const directivesPlugin = {
+    name: NAME,
+    collect(ctx) {
+        ctx.onDirective((report) => {
+            // On the element, which is what the directive was applied to. The component that ran
+            // is only where the call happened.
+            if (!report.target)
+                return;
+            const held = ctx.elementAnnotation(report.target) ?? [];
+            // A render effect re-runs, so the same directive arrives more than once.
+            const already = held.some((n) => n.kind === report.kind && n.name === report.name);
+            if (already)
+                return;
+            held.push({
+                kind: report.kind,
+                name: report.name,
+                element: report.element,
+                ...(report.at ? { at: report.at } : {}),
+            });
+            ctx.annotateElement(report.target, held);
+        });
+    },
+    rows(node) {
+        const notes = node.extra?.[NAME];
+        if (!notes?.length)
+            return [];
+        return notes.map((note) => ({
+            label: label(note),
+            value: note.element,
+            ...(note.at ? { at: note.at } : {}),
+        }));
+    },
+    elementRows(extra) {
+        return directiveRows(directivesOn(extra));
+    },
+    elementBadge(extra) {
+        return directiveBadge(directivesOn(extra));
+    },
+    badge(node) {
+        const notes = node.extra?.[NAME];
+        if (!notes?.length)
+            return undefined;
+        // A badge sits beside a label, so it says which directive and not the whole expression
+        // an inline ref was written as.
+        const first = notes[0];
+        const short = first.kind === 'ref' ? 'ref' : label(first);
+        return notes.length > 1 ? `${short} +${notes.length - 1}` : short;
+    },
+};
+registerDevtoolsPlugin(directivesPlugin);

package/dist/plugins/index.d.ts

@@ -0,0 +1,7 @@
+import './directives.js';
+import './context.js';
+export { directivesPlugin, NAME as DIRECTIVES } from './directives.js';
+export type { DirectiveNote } from './directives.js';
+export { contextPlugin, NAME as CONTEXT } from './context.js';
+export type { ContextNote } from './context.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAKA,OAAO,iBAAiB,CAAC;AACzB,OAAO,cAAc,CAAC;AAEtB,OAAO,EAAE,gBAAgB,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/plugins/index.js

@@ -0,0 +1,9 @@
+// The plugins that ship with devtools.
+//
+// Importing this registers them. Both halves of a plugin live in one module, so an agent in
+// the page and a panel elsewhere import the same thing and each uses the half it can run.
+// A host that wants none of them imports `../plugin.js` directly and registers its own.
+import './directives.js';
+import './context.js';
+export { directivesPlugin, NAME as DIRECTIVES } from './directives.js';
+export { contextPlugin, NAME as CONTEXT } from './context.js';

package/dist/source.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Where a reactive node was created.
+ *
+ * The compiler marks each creation site in development (`sourceLocations`) by calling the
+ * global installed here, just before the statement that makes the node. The instrumented
+ * primitive takes the mark and keeps it on the graph node.
+ *
+ * A single slot, not a stack: in `signal(compute(signal(1)))` the inner call takes the mark
+ * and the outer gets none, rather than claiming a location that is not its own.
+ */
+/** Where in the author's source a node was created. Every field is optional. */
+export interface ReactiveSourceLocation {
+    file?: string;
+    line?: number;
+    column?: number;
+    /** The source text this came from, when the compiler recorded it. Refs carry it. */
+    name?: string;
+    /**
+     * The node came from a dependency rather than from the project. Only ever set when the
+     * compiler was told to mark dependencies too; otherwise they carry no location at all.
+     */
+    external?: boolean;
+    /**
+     * Where this is in the compiled output, when the location above came from a source map.
+     *
+     * Both are worth having. The original says which component and which file; the compiled one
+     * says which of that component's bindings, because a template's holes all map back to the
+     * position the template opens at — one entry per emitted root is all the map has. Until
+     * that changes, the compiled line is the only thing that tells two bindings apart.
+     */
+    compiled?: {
+        line?: number;
+        column?: number;
+    };
+}
+/** A location, plus the variable name the source gave it when there was one. */
+export interface ReactiveSourceMetadata {
+    name?: string;
+    location?: ReactiveSourceLocation;
+}
+/**
+ * Where each component was declared, by name.
+ *
+ * The graph sees the memo the compiler wraps a component in, and all that memo carries back
+ * is the name stamped on what the component returned — so name is the only key available.
+ * Two components sharing a name are recorded as ambiguous and reported as unknown, since a
+ * location pointing at the wrong file is worse than none.
+ */
+/**
+ * Record where the next node is about to be created. The compiler calls this; call it
+ * yourself only for a node the compiler cannot see, immediately before the primitive.
+ */
+export declare function markReactiveSource(file?: string, line?: number, column?: number, name?: string): void;
+/** Record where a component was declared. The compiler calls this. */
+export declare function markComponentSource(name: string, file?: string, line?: number, column?: number): void;
+/** Where a component of this name was declared, when exactly one was. */
+export declare function componentSource(name: string): ReactiveSourceLocation | undefined;
+/**
+ * Reading keeps it for the rest of the turn.
+ *
+ * One statement can make several nodes: `createStore({ a, b })` builds a signal per key
+ * inside the framework, and all of them belong to the line that asked for the store. So the
+ * mark survives the read and is dropped on the next microtask, which is the end of the
+ * statement that left it as far as anything synchronous is concerned.
+ */
+export declare function takeReactiveSource(): ReactiveSourceMetadata | null;
+/** Where the props of this object were written, when the compiler recorded them. */
+export declare function propsLocations(props: unknown): Record<string, [number, number]> | undefined;
+/** The hole an accessor came from, when the compiler marked it. */
+export declare function holeLocation(accessor: unknown): ReactiveSourceLocation | undefined;
+export declare function installSourceMarker(): void;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CACnC;AAgCD;;;;;;;GAOG;AAGH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAQrG;AAYD,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAQrG;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,sBAAsB,GAAG,IAAI,CAelE;AA4CD,oFAAoF;AACpF,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,GACb,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAE9C;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,sBAAsB,GAAG,SAAS,CAGlF;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C"}