@adea-ai/themes 0.4.0 → 0.4.2

package/dist/schema.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The canonical schema.
+ *
+ * This file is the contract. Everything else in the package — the normalizer, the
+ * Base24 bridge, the terminal and editor adapters — exists to move values into or
+ * out of the shapes declared here, and no adapter is allowed to invent a role that
+ * is not in this file.
+ *
+ * ## Why this and not Base24
+ *
+ * Base24 is an excellent interchange format and a poor application schema. Its
+ * sixteen `base00`–`base0F` slots describe an editor: there is a slot for the
+ * background, a slot for comments, and a slot for the colour of a deprecated API,
+ * but nothing that means "the surface one step above the card" or "the text a
+ * caption uses". A UI built by reading Base24 directly ends up with component
+ * authors choosing between `base01` and `base02` by eye, which is how a design
+ * system acquires four nearly-identical greys that no one dares consolidate.
+ *
+ * So the roles below are the ones a component actually asks for — a surface, a
+ * border, a muted text, an accent — and Base24 is a bridge at the edge. See
+ * `adapters/base24.ts` for both directions.
+ *
+ * ## Why OKLCH strings and not numbers
+ *
+ * Every colour here is an `oklch(L C H)` string rather than a parsed object. It
+ * keeps the catalogue readable and diffable in review, it can be handed straight
+ * to CSS with no serialisation step, and it cannot be mutated by a consumer that
+ * receives it. Call {@link "../oklch".parseColor} when the numbers are needed.
+ */
+/** Whether a theme is a light or a dark theme. */
+export type ThemeAppearance = 'dark' | 'light';
+/**
+ * The seventeen colours that describe a surface.
+ *
+ * The set is deliberately small and deliberately semantic. There is no `grey300`
+ * and no `blue500`: a component that needs "a slightly raised panel" asks for
+ * `surfaceElevated` and gets whichever value the active theme considers one step
+ * up, at every theme in the catalogue, without the component knowing.
+ */
+export interface AdeaThemeColors {
+    /** The canvas. Everything that is not a surface sits on this. */
+    background: string;
+    /** Default body text on `background`. Clears 4.5:1 against it in every theme. */
+    foreground: string;
+    /** The first rung above the canvas: cards, panels, sidebars. */
+    surface: string;
+    /** The second rung: popovers, dialogs, menus floating above a card. */
+    surfaceElevated: string;
+    /** A surface under the pointer. */
+    surfaceHover: string;
+    /** A surface under an active press or a selected row. */
+    surfaceActive: string;
+    /** The default divider and input outline. */
+    border: string;
+    /** A divider that should recede: table rules, separators inside a card. */
+    borderMuted: string;
+    /** Text at full strength. Identical to `foreground` unless a theme overrides it. */
+    text: string;
+    /** Secondary text: descriptions, captions, table cell metadata. Clears 4.5:1. */
+    textMuted: string;
+    /**
+     * Tertiary text: timestamps, counts, placeholder copy. Clears 3:1, which is the
+     * WCAG floor for large text and for non-essential text — the floor is lower
+     * here on purpose, because at 4.5:1 there is no longer any visual difference
+     * between this role and `textMuted` and the role stops earning its place.
+     */
+    textSubtle: string;
+    /** The one interactive colour: primary buttons, selected tabs, focus rings. */
+    accent: string;
+    /** Text and icons drawn on top of `accent`. Clears 4.5:1 against it. */
+    accentForeground: string;
+    /** Positive status. Text-legible against `background`, unlike most palettes' green. */
+    success: string;
+    /** Cautionary status. Text-legible against `background`. */
+    warning: string;
+    /** Destructive status and destructive text. Text-legible against `background`. */
+    error: string;
+    /** Neutral notice. Text-legible against `background`. */
+    info: string;
+}
+/**
+ * The sixteen ANSI colours.
+ *
+ * Carried in the canonical schema rather than derived on demand because they are
+ * what a shell, a diff and a build log are coloured with, and a terminal embedded
+ * in the app must agree with the terminal the user has open beside it. When a
+ * theme is imported from a palette that publishes ANSI values, these are those
+ * values, not a reconstruction.
+ */
+export interface AdeaAnsi {
+    black: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    magenta: string;
+    cyan: string;
+    white: string;
+    brightBlack: string;
+    brightRed: string;
+    brightGreen: string;
+    brightYellow: string;
+    brightBlue: string;
+    brightMagenta: string;
+    brightCyan: string;
+    brightWhite: string;
+}
+/**
+ * A theme.
+ *
+ * This is the published contract: the three identity fields, the seventeen surface
+ * roles, the sixteen ANSI colours, and the two state colours a selection needs.
+ */
+export interface AdeaTheme {
+    /** Stable id. The `data-theme` value and what a preference stores. */
+    id: string;
+    /** Human-readable name, e.g. `"Catppuccin Mocha"`. */
+    name: string;
+    appearance: ThemeAppearance;
+    colors: AdeaThemeColors;
+    ansi: AdeaAnsi;
+    /** The text cursor. Usually the foreground, but a palette may disagree. */
+    cursor: string;
+    /** The selection background. */
+    selection: string;
+}
+/** Where a palette came from and the terms it is used under. */
+export interface ThemeProvenance {
+    /** The project or person the palette belongs to. */
+    project: string;
+    /** The canonical upstream URL. */
+    url: string;
+    /** An SPDX identifier. Every palette in this catalogue is permissive. */
+    license: string;
+    /**
+     * The commit the vendored values were taken from, when they were taken from a
+     * vendored artefact rather than from the project directly. This is what makes
+     * the palette data auditable: the numbers in `palettes/` can be re-derived from
+     * a named revision rather than trusted.
+     */
+    revision?: string;
+    /** The upstream artefacts this palette's ANSI half was bootstrapped from. */
+    bootstrappedFrom?: readonly string[];
+}
+/**
+ * A catalogue entry: the theme, plus what a picker and an audit need.
+ *
+ * Kept as a separate type rather than folded into {@link AdeaTheme} so that a
+ * consumer receiving a theme can depend on exactly the documented contract and
+ * nothing else, while the catalogue still carries the provenance that lets a
+ * licence audit answer "where did this colour come from".
+ */
+export interface AdeaThemeRecord extends AdeaTheme {
+    /** Groups the variants that came from one project, e.g. `catppuccin`. */
+    family: string;
+    /** How the family is written in a picker, e.g. `Catppuccin`. */
+    familyLabel: string;
+    /** Short display name within the family, e.g. `Mocha`. */
+    label: string;
+    /** One line, shown in a picker. */
+    description: string;
+    provenance: ThemeProvenance;
+    /** Search and filter terms, e.g. `['dark', 'muted', 'popular']`. */
+    tags: readonly string[];
+}
+/** A family of themes: one project, one or more variants. */
+export interface ThemeFamily {
+    id: string;
+    label: string;
+    themes: readonly AdeaThemeRecord[];
+}
+/** The keys of {@link AdeaThemeColors}, for iteration and validation. */
+export declare const THEME_COLOR_KEYS: readonly ["background", "foreground", "surface", "surfaceElevated", "surfaceHover", "surfaceActive", "border", "borderMuted", "text", "textMuted", "textSubtle", "accent", "accentForeground", "success", "warning", "error", "info"];
+/** The keys of {@link AdeaAnsi}. */
+export declare const ANSI_KEYS: readonly ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite"];
+export type ThemeColorKey = (typeof THEME_COLOR_KEYS)[number];
+export type AnsiKey = (typeof ANSI_KEYS)[number];
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

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

package/dist/schema.js

@@ -0,0 +1,69 @@
+/**
+ * The canonical schema.
+ *
+ * This file is the contract. Everything else in the package — the normalizer, the
+ * Base24 bridge, the terminal and editor adapters — exists to move values into or
+ * out of the shapes declared here, and no adapter is allowed to invent a role that
+ * is not in this file.
+ *
+ * ## Why this and not Base24
+ *
+ * Base24 is an excellent interchange format and a poor application schema. Its
+ * sixteen `base00`–`base0F` slots describe an editor: there is a slot for the
+ * background, a slot for comments, and a slot for the colour of a deprecated API,
+ * but nothing that means "the surface one step above the card" or "the text a
+ * caption uses". A UI built by reading Base24 directly ends up with component
+ * authors choosing between `base01` and `base02` by eye, which is how a design
+ * system acquires four nearly-identical greys that no one dares consolidate.
+ *
+ * So the roles below are the ones a component actually asks for — a surface, a
+ * border, a muted text, an accent — and Base24 is a bridge at the edge. See
+ * `adapters/base24.ts` for both directions.
+ *
+ * ## Why OKLCH strings and not numbers
+ *
+ * Every colour here is an `oklch(L C H)` string rather than a parsed object. It
+ * keeps the catalogue readable and diffable in review, it can be handed straight
+ * to CSS with no serialisation step, and it cannot be mutated by a consumer that
+ * receives it. Call {@link "../oklch".parseColor} when the numbers are needed.
+ */
+/** The keys of {@link AdeaThemeColors}, for iteration and validation. */
+export const THEME_COLOR_KEYS = [
+    'background',
+    'foreground',
+    'surface',
+    'surfaceElevated',
+    'surfaceHover',
+    'surfaceActive',
+    'border',
+    'borderMuted',
+    'text',
+    'textMuted',
+    'textSubtle',
+    'accent',
+    'accentForeground',
+    'success',
+    'warning',
+    'error',
+    'info',
+];
+/** The keys of {@link AdeaAnsi}. */
+export const ANSI_KEYS = [
+    'black',
+    'red',
+    'green',
+    'yellow',
+    'blue',
+    'magenta',
+    'cyan',
+    'white',
+    'brightBlack',
+    'brightRed',
+    'brightGreen',
+    'brightYellow',
+    'brightBlue',
+    'brightMagenta',
+    'brightCyan',
+    'brightWhite',
+];
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAuJH,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,YAAY;IACZ,YAAY;IACZ,SAAS;IACT,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,QAAQ;IACR,aAAa;IACb,MAAM;IACN,WAAW;IACX,YAAY;IACZ,QAAQ;IACR,kBAAkB;IAClB,SAAS;IACT,SAAS;IACT,OAAO;IACP,MAAM;CAC+C,CAAA;AAEvD,oCAAoC;AACpC,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,OAAO;IACP,KAAK;IACL,OAAO;IACP,QAAQ;IACR,MAAM;IACN,SAAS;IACT,MAAM;IACN,OAAO;IACP,aAAa;IACb,WAAW;IACX,aAAa;IACb,cAAc;IACd,YAAY;IACZ,eAAe;IACf,YAAY;IACZ,aAAa;CACiC,CAAA"}

package/dist/sources.d.ts

@@ -0,0 +1,296 @@
+/**
+ * What the catalogue contains, and where each palette came from.
+ *
+ * Two lists. {@link VENDORED_SOURCES} names the Base24 schemes that
+ * `scripts/vendor-palettes.ts` reproduces from upstream, and {@link AUTHORED_SOURCES}
+ * is Adea's own theme, which has no upstream to vendor from. Together they are the
+ * catalogue's input; `scripts/build-catalogue.ts` runs them all through the
+ * normalizer and writes the committed output.
+ *
+ * ## Provenance is per-family, and it was checked rather than assumed
+ *
+ * Every licence below was read from the upstream repository, not recalled. Two
+ * needed care:
+ *
+ * - **Gruvbox** declares MIT/X11 in its README and ships no `LICENSE` file, so
+ *   GitHub's detector reports nothing. The README is the licence grant and it is
+ *   recorded as MIT.
+ * - **Monokai** has no permissively licensed repository of its own: the repository
+ *   under the Monokai organisation carries no licence at all. The *values* in the
+ *   catalogue are therefore taken from the MIT-licensed iTerm2-Color-Schemes port,
+ *   which is the artefact recorded as the licence basis, and Monokai is credited
+ *   as the design's origin. See NOTICE for the full reasoning.
+ *
+ * ## The chain of custody
+ *
+ * These palettes reach the catalogue through one intermediate artefact, and the
+ * honest description of that is: `palettes/<id>.json` holds values reproduced from
+ * a Base24 scheme in the `oklch-terminal-themes` dataset at a pinned revision,
+ * which is itself derived from `iTerm2-Color-Schemes` at a pinned revision, which
+ * is where the per-family values were first published as terminal schemes. Each
+ * family's official project is recorded as the design's origin, and the values were
+ * checked against those projects' published palettes — the backgrounds and
+ * foregrounds of all fourteen families match the official palettes exactly.
+ *
+ * `tests/provenance.test.ts` holds those official values as assertions, so the
+ * claim "this is really Catppuccin Mocha" fails the build rather than drifting.
+ */
+import type { Base24Slot } from './adapters/base24';
+import type { ThemeAppearance, ThemeProvenance } from './schema';
+/** The dataset the Base24 schemes are reproduced from. */
+export declare const CATALOGUE_REPOSITORY = "https://github.com/williamzujkowski/oklch-terminal-themes";
+/**
+ * The pinned revision. Refreshing the catalogue starts by changing this, which is
+ * what makes a palette update a reviewable diff rather than an invisible drift.
+ */
+export declare const CATALOGUE_REVISION = "9e800e7fe760081d4c10317498038ed4227341d6";
+/** Where Adea's own theme lives. */
+export declare const ADEA_PROVENANCE: ThemeProvenance;
+/**
+ * A theme composed from **two** upstream palettes.
+ *
+ * Adea's own dark theme is not a copy of any published palette, and it is not
+ * hand-authored either. It is a deliberate composition: the canvas, the greys, the
+ * cursor and the selection come from a palette chosen for exactly those — Aardvark
+ * Ink, whose near-black navy and muted blue-grey foreground are why it was picked —
+ * and the sixteen ANSI hues come from a second palette chosen for its saturation,
+ * GitHub's dark scheme.
+ *
+ * The split exists because the two properties are in tension inside one palette. A
+ * palette tuned for a comfortable canvas mutes its hues to agree with it; a palette
+ * tuned for vivid syntax colours tends to sit on a canvas that is very dark or very
+ * flat. Taking one of each yields a calm ground with legible colour on it.
+ *
+ * ## Why it is composed rather than merged by hand
+ *
+ * The alternative was to read both palettes and paste the merged hex into
+ * `palettes/adea-dark.json`. That works once and is wrong afterwards: nothing then
+ * records which donor each value came from, so neither donor could ever be
+ * refreshed. Composing in the vendor step keeps both parents named, keeps the values
+ * upstream's own bytes rather than a transcription, and makes "GitHub changed its
+ * blue" a one-line diff plus a rebuild.
+ */
+export interface ComposedSource {
+    id: string;
+    name: string;
+    family: 'adea';
+    familyLabel: string;
+    label: string;
+    description: string;
+    appearance: ThemeAppearance;
+    tags: readonly string[];
+    /** The two donors' slugs in the dataset, and which half each supplies. */
+    donors: Readonly<Record<'structure' | 'hues', string>>;
+    /**
+     * The Base24 slot map.
+     *
+     * Each entry is `[donor, key]`, where the donor is `structure` or `hues` and the
+     * key is a role name in that donor's published palette — the dataset's own names,
+     * so `purple` is Base24's magenta slot and `brightPurple` its bright magenta.
+     */
+    slots: Readonly<Partial<Record<Base24Slot, readonly ['structure' | 'hues', string]>>>;
+    /**
+     * Slots neither donor supplies, derived from one of them.
+     *
+     * `slots` and `synthesise` are jointly total: between them they must cover every
+     * Base24 slot, and the vendor step asserts that rather than trusting it. The two
+     * are separate maps rather than one so that "this value came from a donor" and
+     * "this value was computed" stay distinguishable in review.
+     */
+    synthesise: Readonly<Partial<Record<Base24Slot, readonly ['structure' | 'hues', string, {
+        rotate?: number;
+        lighten?: number;
+    }]>>>;
+    /**
+     * ANSI roles pinned to the structure donor's own values.
+     *
+     * The greyscale ramp is normally *derived* by ranking a scheme's grey slots by
+     * measured contrast, because Base24 does not name `black`, `white` or
+     * `brightBlack` and light schemes invert them. That derivation is right for an
+     * imported palette and wrong here: Aardvark Ink publishes a greyscale it chose,
+     * the greyscale is the reason it was chosen as the structure donor, and
+     * re-deriving it gives back something close but not equal. So the four roles are
+     * pinned to the donor's own values instead.
+     */
+    ansiFromStructure: readonly ('black' | 'brightBlack' | 'white' | 'brightWhite')[];
+    /** The role supplying the accent, when the family's identity demands one. */
+    accentSlot?: 'blue' | 'magenta' | 'cyan' | 'green';
+    palette?: Partial<Record<Base24Slot, string>>;
+    /**
+     * Transpose this composition's hues onto the borrowed canvas.
+     *
+     * Set when a composition takes its hues from a palette authored against a different
+     * kind of canvas — which is what borrowing a *dark* palette's hues for a *light*
+     * canvas is. See `transposeHues` in `src/normalize.ts` for why the whole hue set
+     * moves by one common step rather than each hue being repaired on its own.
+     */
+    hueTranspose?: {
+        floor: number;
+    };
+    /** The body-text floor; the defaults are held to AAA rather than the catalogue's AA. */
+    textFloor?: number;
+    provenance: ThemeProvenance;
+}
+/**
+ * Adea's two default themes.
+ *
+ * Both are compositions and both were previously authored here — the light one as a
+ * neutral grey ramp on white with a monochrome accent, the dark one as a neutral grey
+ * ramp on `#252525`. They replaced those entirely while keeping their names, because
+ * they are the defaults: the system's own appearance, not a pair of options beside it.
+ *
+ * ## Why they are a *pair* rather than two themes
+ *
+ * They share one hue donor, so a red is the same red and a blue the same blue in both,
+ * and each borrows its canvas from a palette chosen for the *canvas* rather than for
+ * its colours:
+ *
+ * | | canvas | canvas hue | hues |
+ * | --- | --- | --- | --- |
+ * | Adea Dark | Aardvark Ink `#0f141f` | 265° | GitHub Dark Default |
+ * | Adea Light | Nord Light `#e3e9f4` | 262° | GitHub Dark Default |
+ *
+ * Three degrees apart, and both canvases are *tinted* rather than neutral — 0.024 and
+ * 0.016 of chroma — which is the property that makes the pair feel like one theme seen
+ * at two exposures instead of two themes that happen to ship together. Switching
+ * appearance changes lightness and nothing else about the theme's identity; that claim
+ * is asserted in `tests/provenance.test.ts` rather than left as intent.
+ *
+ * The light theme is the reason `hueTranspose` exists: GitHub's dark hues measure
+ * between 2.5:1 and 4.1:1 on a light canvas, so the whole hue set is transposed down in
+ * lightness by one common step — hue and chroma intact, relative brightness ordering
+ * intact — rather than repaired hue by hue, which would have collapsed every bright
+ * variant onto its normal sibling.
+ */
+export declare const COMPOSED_SOURCES: readonly ComposedSource[];
+/**
+ * Per-family provenance.
+ *
+ * `url` is the project's own repository — the place its palette is defined — while
+ * the vendored values come through the chain described in this module's header.
+ * Recording both is the point: one answers "whose palette is this", the other
+ * answers "which bytes are in the file".
+ */
+export declare const FAMILY_PROVENANCE: Readonly<Record<string, ThemeProvenance>>;
+/** A theme that is normalized from a vendored Base24 scheme. */
+export interface VendoredSource {
+    id: string;
+    /** The scheme's slug in the dataset. */
+    slug: string;
+    family: keyof typeof FAMILY_PROVENANCE;
+    familyLabel: string;
+    label: string;
+    name: string;
+    description: string;
+    appearance: ThemeAppearance;
+    tags: readonly string[];
+    /** Declared when the family's identity is not in its blue slot. */
+    accentSlot?: 'blue' | 'magenta' | 'cyan' | 'green';
+    /**
+     * Corrections to the vendored scheme, applied before normalization.
+     *
+     * One entry uses this, and it is worth reading as the example of when it is
+     * legitimate: iTerm2's One Dark port deliberately darkens the canvas to `#21252b`
+     * so a terminal reads as a distinct surface, but Atom's own editor palette — the
+     * thing "One Dark" means — is `hsl(220, 13%, 18%)` = `#282c34`, with comments at
+     * `#5c6370` rather than the port's `#767676`. Adea themes an application, so the
+     * project's value is the correct one. Every correction is reported as a finding
+     * and appears in the catalogue's build log.
+     */
+    palette?: Partial<Record<Base24Slot, string>>;
+}
+/**
+ * The vendored catalogue.
+ *
+ * Ordered family by family, and within a family light-to-dark or by the order the
+ * project itself lists its flavours. The order is the order a picker shows, so it
+ * is deliberate rather than alphabetical.
+ */
+export declare const VENDORED_SOURCES: readonly VendoredSource[];
+/**
+ * Adea's own theme.
+ *
+ * Authored here rather than vendored, and the only entry whose colours are chosen
+ * rather than reproduced. It is deliberately a neutral ladder with a monochrome
+ * accent — the design system's default has to work as a default for everyone, which
+ * means it cannot be anybody's favourite colour.
+ *
+ * Intentionally empty, and worth leaving that way until something needs it.
+ *
+ * This was where both default themes lived. They are now
+ * {@link COMPOSED_SOURCES} entries instead, which is a better home for them: a
+ * composition names the upstream palettes it came from and can be rebuilt when either
+ * moves, while an authored entry is a table of values nobody can refresh.
+ *
+ * The route stays because it is the only way to specify *semantic* roles directly
+ * rather than deriving them through Base24 slots — which is what a brand theme with
+ * values handed over by a designer would need. Nothing uses it today; if nothing has by
+ * the time someone reads this, delete it.
+ */
+export interface AuthoredSource {
+    id: string;
+    family: string;
+    familyLabel: string;
+    label: string;
+    name: string;
+    description: string;
+    appearance: ThemeAppearance;
+    tags: readonly string[];
+    /**
+     * The greyscale ramp the theme is built from, darkest first.
+     *
+     * Authored as hex rather than OKLCH because that is how the design system's
+     * values were originally specified and reviewed; the normalizer converts, and the
+     * committed catalogue is OKLCH.
+     */
+    ramp: {
+        background: string;
+        foreground: string;
+        surface: string;
+        surfaceElevated: string;
+        surfaceHover: string;
+        surfaceActive: string;
+        border: string;
+        borderMuted: string;
+        textMuted: string;
+        textSubtle: string;
+    };
+    accent: string;
+    accentForeground: string;
+    status: {
+        success: string;
+        warning: string;
+        error: string;
+        info: string;
+    };
+    /**
+     * The terminal palette.
+     *
+     * Adea ships a terminal, so its own theme has to answer the sixteen ANSI
+     * questions the same way an imported theme does. These are the values the product
+     * already runs: the light set is GitHub's light scheme and the dark set GitHub's
+     * dark, which is what the embedded terminal was drawn against.
+     */
+    ansi: {
+        black: string;
+        red: string;
+        green: string;
+        yellow: string;
+        blue: string;
+        magenta: string;
+        cyan: string;
+        white: string;
+        brightBlack: string;
+        brightRed: string;
+        brightGreen: string;
+        brightYellow: string;
+        brightBlue: string;
+        brightMagenta: string;
+        brightCyan: string;
+        brightWhite: string;
+    };
+    cursor: string;
+    selection: string;
+}
+export declare const AUTHORED_SOURCES: readonly AuthoredSource[];
+//# sourceMappingURL=sources.d.ts.map

package/dist/sources.d.ts.map

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