@acornly/core 0.1.0 → 0.3.0

package/dist/anchoring/profiles.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Site profiles: most sites the generic engine cannot see well need no code of their own, only a
+ * description of where their stable units are (the lines of a diff, keyed by line number). A
+ * profile is that description as plain JSON, read by one built-in anchor provider, `profile`. See
+ * the design doc's "Hard pages in M7 > Anchor providers".
+ *
+ * A profile names the sites it is for (`hosts`, `paths`) and, with CSS selectors only, the units
+ * (`unit`), what each unit's key is read from (`key`) and where its text is (`text`). No profile
+ * field is code or a regular expression, so a profile can be checked (`validateProfile`) and come
+ * from a list the extension did not ship with.
+ *
+ * The provider describes a text selection inside one unit as `{ profile, rev, unit, start, end }`:
+ * the profile's name and revision, the unit's key, and offsets in the unit's normalized text. To
+ * resolve, it finds the unit by key and checks that the offsets still cover the note's stored quote;
+ * when they don't, it looks for the quote in the same unit, then (with `follow`) in the other units,
+ * nearest key first, which is how a note on a line follows it to a newer commit. Anything else is
+ * left to the generic engine: a selection across units, a note without a quote, a page whose units
+ * are not rendered yet.
+ */
+import { type AnchorProvider, type AnchorProviders, type ProviderContext, type ProviderMatch } from "./providers.js";
+import type { ProviderTarget } from "./provider-stage.js";
+export { FIRST_PARTY_PROFILES, GITHUB_DIFF_PROFILE } from "./site-profiles.js";
+/** One step from a unit to the element its key is read from. Applied in this order: `closest`,
+ * then `prev`, then `in`; each is a CSS selector. */
+export interface ProfileKeyPart {
+    /** The nearest ancestor matching this, the unit itself included. */
+    closest?: string;
+    /** The nearest earlier sibling matching this. */
+    prev?: string;
+    /** The first descendant matching this. */
+    in?: string;
+    /** The attribute holding the key (`id`, `data-line-number`). */
+    attr: string;
+}
+/** A site profile: plain JSON, at most PROFILE_MAX characters. */
+export interface SiteProfile {
+    /** Stored in every selector it writes: lower case letters, digits and dashes, starting with a
+     * letter, at most 40 characters. */
+    name: string;
+    /** The key format revision, a positive integer: raise it when `unit` or `key` change meaning.
+     * Selectors written at a higher revision are left to the generic engine. */
+    rev: number;
+    /** Host names, lower case: `github.com`, or `*.example.com` for its subdomains. */
+    hosts: readonly string[];
+    /**
+     * Path patterns, each starting with `/`: `*` is one path segment, a final `**` is any number of
+     * them, anything else is literal. Default: every path.
+     */
+    paths?: readonly string[];
+    /** The units: a CSS selector. */
+    unit: string;
+    /** Where a unit's key comes from: one to three parts, joined with `:`. */
+    key: readonly ProfileKeyPart[];
+    /** The text of a unit: the first descendant matching this CSS selector. Default the unit. */
+    text?: string;
+    /** Whether a note whose unit lost its text may move to another unit holding it. */
+    follow?: boolean;
+}
+/** What the profile provider stores in its ProviderSelector. */
+export interface ProfileValue {
+    /** The profile's name. */
+    profile: string;
+    /** The profile's `rev` when it was written. */
+    rev: number;
+    /** The unit's key. */
+    unit: string;
+    /** Offsets in the unit's normalized text. */
+    start: number;
+    end: number;
+}
+/** Longest a profile may be, as JSON text. */
+export declare const PROFILE_MAX: number;
+/** The name of the provider that reads profiles. */
+export declare const PROFILE_PROVIDER = "profile";
+/** Default time one resolve may take before it leaves the note to the generic engine: well under
+ * the registry's budget, so no stored value can get the provider turned off for the page. */
+export declare const PROFILE_RESOLVE_MS = 8;
+/** Thrown by `validateProfile` for a malformed profile. */
+export declare class ProfileError extends TypeError {
+    constructor(message: string);
+}
+/**
+ * Checks a profile and returns a frozen copy of it. Throws a ProfileError for anything but plain
+ * JSON of the shape above within PROFILE_MAX characters: unknown fields, a path pattern that is not
+ * one, a selector that is not valid CSS. Selectors are parsed with `document` (default the global
+ * one); where there is none (a service worker), only their form is checked, and a selector the page
+ * later refuses turns that profile off for the page.
+ */
+export declare function validateProfile(input: unknown, document?: Document | undefined): Readonly<SiteProfile>;
+/** Whether `profile` is for this URL. */
+export declare function profileMatches(profile: Readonly<SiteProfile>, url: URL): boolean;
+export interface ProfileProviderOptions {
+    /** Longest one resolve may look before it leaves the note to the generic engine, in
+     * milliseconds. Default PROFILE_RESOLVE_MS. */
+    limitMs?: number;
+    /** The clock, for tests. Default `performance.now`. */
+    now?: () => number;
+}
+/**
+ * The `profile` provider: reads every profile added to it. The core keeps one for the page
+ * (`profileProvider`, registered by `registerAnchorProfiles`); tests and embedders can make their
+ * own.
+ */
+export declare class ProfileProvider implements AnchorProvider {
+    readonly name = "profile";
+    readonly version = 1;
+    /** By the object it was added as, so adding the same list again (two SDK instances) is counted. */
+    private readonly entries;
+    private readonly now;
+    private readonly limitMs;
+    constructor(profiles?: readonly unknown[], options?: ProfileProviderOptions);
+    /**
+     * Adds profiles; returns a function that removes them. Throws a ProfileError, adding none, for a
+     * malformed profile or another one of the same name. A registry that already asked `matches`
+     * keeps its answer until told otherwise: use `registerAnchorProfiles`, or call the registry's
+     * `rematch` after adding to a registered provider.
+     */
+    add(profiles: readonly unknown[]): () => void;
+    /** The profiles added, in the order they were added. */
+    get profiles(): Readonly<SiteProfile>[];
+    matches(url: URL): boolean;
+    describe(target: ProviderTarget, context: ProviderContext): ProfileValue | null;
+    resolve(value: unknown, _version: number, context: ProviderContext): ProviderMatch | null;
+    /** Per document: the profiles whose selectors it refused. */
+    private readonly refused;
+    /**
+     * Runs one profile's work; a selector the page's engine refuses (checked without a DOM, or
+     * syntax this browser lacks) turns only that profile off for the document.
+     */
+    private guard;
+}
+/** The page's profile provider. */
+export declare const profileProvider: ProfileProvider;
+/**
+ * Adds site profiles for the page and registers the `profile` provider with the page's providers
+ * (`anchorProviders`). Returns a function that removes them. Throws a ProfileError for a malformed
+ * profile, or another of the same name; nothing is added then.
+ */
+export declare function registerAnchorProfiles(profiles: readonly unknown[], providers?: AnchorProviders): () => void;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/anchoring/profiles.d.ts.map

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