@panda-lingo/goldendict 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @panda-lingo/goldendict
+
+Framework-independent client and `<goldendict-view>` renderer for the
+GoldenDict REST service. The package preserves GoldenDict-ng article markup and
+styles inside a sandboxed iframe while exposing typed browser events and brand
+theme tokens.
+
+```ts
+import {
+  DictionaryClient,
+  defineGoldendictView,
+} from "@panda-lingo/goldendict";
+
+defineGoldendictView();
+const view = document.querySelector("goldendict-view");
+view.client = new DictionaryClient({ baseUrl: "/api/v1" });
+await view.lookup("example");
+```
+
+Importing the package registers `<goldendict-view>` automatically. Call
+`defineGoldendictView("my-dictionary-view")` when a custom tag name is useful.
+
+The public API includes:
+
+- `DictionaryClient` for dictionary listing and lookup, plus the backend's
+  explicitly opt-in server-path load operation.
+- `GoldenDictView` and `defineGoldendictView` for framework-independent use.
+- `GoldenDictTheme`, light/dark token presets, and `themeToCss` for branding.
+- `GOLDENDICT_EVENTS` for lookup, active article, collapse, media, external-link,
+  and state notifications.
+- Resource/link helpers for hosts that need to inspect GoldenDict URLs.
+
+Dictionary scripts are removed by default (`scriptPolicy = "none"`). The
+explicit `"sandboxed"` policy retains them inside the iframe, which never gets
+`allow-same-origin`. Lookup, media, and external-link events are cancelable so a
+host application can replace the default navigation behavior.
+
+In sandboxed mode, external sidecars such as `bres://.../Dictionary-UI.js` are
+routed through the article's `resourceBaseUrl` without changing filename case.
+Because the iframe has an opaque origin, dictionary XHR/fetch requests send
+`Origin: null`; the read-only API must explicitly allow that origin when this
+compatibility mode is enabled. Classic script element loads do not grant the
+dictionary access to the host document.
+
+Run the package demo from the workspace root with `npm run dev`. It discovers
+the dictionaries loaded from the backend's configured local paths at startup.
+
+GoldenDict-ng CSS and icons are pinned and sync-managed. See
+[`UPGRADING_GOLDENDICT.md`](./UPGRADING_GOLDENDICT.md) for the one-command local
+checkout upgrade flow.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,10 @@
+# Third-party notices
+
+The GoldenDict article styles and icons under `src/styles/vendor` and
+`src/assets/icons` are derived from GoldenDict-ng commit
+`5ad66765aa423d381025566bff990f7d8007be84`.
+
+GoldenDict-ng is licensed under GNU GPL version 3 or later. Copyright notices
+and the complete license text are retained in this package's `LICENSE` file.
+
+Upstream project: https://github.com/xiaoyifang/goldendict-ng

package/UPGRADING_GOLDENDICT.md

@@ -0,0 +1,33 @@
+# Updating GoldenDict-ng rendering compatibility
+
+Vendored upstream files have an explicit boundary:
+
+- `src/styles/vendor/` contains unmodified GoldenDict-ng article CSS.
+- `src/assets/icons/` contains the upstream icons used by that CSS and article HTML.
+- `compatibility/goldendict-ng.json` pins the repository commit and SHA-256 of every copied file.
+- Hand-written browser adapters live elsewhere in `src/` and are never overwritten by sync.
+
+To adopt a newer or modified local GoldenDict-ng checkout:
+
+```sh
+npm run sync:goldendict --workspace @panda-lingo/goldendict -- \
+  --source /path/to/goldendict-ng
+npm test
+npm run build
+```
+
+The sync command copies only manifest-listed files, records their new checksums,
+and pins the checkout's origin, current Git commit, relevant dirty state, and
+diff hash. This also makes an intentional local modification visible instead of
+mislabeling it as an unmodified upstream commit. Review the vendor and manifest diff.
+If upstream adds a stylesheet or required icon, add its source/target mapping to
+the manifest and expose it from `styles/fidelity.ts` or `assets.ts`; the
+compatibility contract test is intended to make omissions visible.
+
+CI and local builds run the target-only checksum check automatically. To also
+verify a checkout matches the currently pinned version:
+
+```sh
+npm run check:goldendict --workspace @panda-lingo/goldendict -- \
+  --source /path/to/goldendict-ng
+```

package/dist/assets.d.ts

@@ -0,0 +1,4 @@
+export declare const BUILTIN_ASSET_URLS: Readonly<Record<string, string>>;
+export declare function resolveBuiltinAsset(url: string): string | undefined;
+export declare function rewriteBuiltinAssetUrls(css: string): string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgB/D,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK3D"}

package/dist/client/dictionary-client.d.ts

@@ -0,0 +1,18 @@
+import type { DictionaryClientOptions, DictionarySummary, LoadDictionaryRequest, LoadDictionaryResponse, LookupOptions, LookupResponse } from "../types";
+export declare class DictionaryApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+export declare class DictionaryClient {
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private readonly headers;
+    private readonly credentials;
+    constructor(options?: DictionaryClientOptions);
+    listDictionaries(signal?: AbortSignal): Promise<DictionarySummary[]>;
+    loadDictionary(input: LoadDictionaryRequest, signal?: AbortSignal): Promise<LoadDictionaryResponse>;
+    lookup(word: string, options?: LookupOptions): Promise<LookupResponse>;
+    private request;
+}
+//# sourceMappingURL=dictionary-client.d.ts.map

package/dist/client/dictionary-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dictionary-client.d.ts","sourceRoot":"","sources":["../../src/client/dictionary-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,aAAa,EACb,cAAc,EACf,MAAM,UAAU,CAAC;AAElB,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAM5D;AAiDD,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,OAAO,GAAE,uBAA4B;IAW3C,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAQpE,cAAc,CAClB,KAAK,EAAE,qBAAqB,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC;IA6B5B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;YAsBlE,OAAO;CAoCtB"}

package/dist/element/goldendict-view.d.ts

@@ -0,0 +1,59 @@
+import { DictionaryClient } from "../client/dictionary-client";
+import type { DictionaryClientOptions, GoldenDictTheme, LookupResponse, ScriptPolicy, ViewState } from "../types";
+export declare class GoldenDictView extends HTMLElement {
+    static readonly observedAttributes: string[];
+    readonly instanceId: string;
+    private readonly frame;
+    private readonly statusElement;
+    private readonly brandElement;
+    private readonly brandImage;
+    private readonly brandText;
+    private clientValue;
+    private requestController?;
+    private requestSequence;
+    private responseValue?;
+    private themeValue;
+    private stateValue;
+    private dictionaryIdsValue;
+    private pendingAnchor?;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    get apiBase(): string;
+    set apiBase(value: string);
+    get client(): DictionaryClient;
+    set client(value: DictionaryClient);
+    get theme(): GoldenDictTheme;
+    set theme(value: GoldenDictTheme);
+    get scriptPolicy(): ScriptPolicy;
+    set scriptPolicy(value: ScriptPolicy);
+    get dictionaryIds(): readonly string[];
+    set dictionaryIds(value: readonly string[]);
+    get state(): ViewState;
+    get response(): LookupResponse | undefined;
+    configureClient(options: DictionaryClientOptions): void;
+    lookup(word: string, dictionaryIds?: readonly string[]): Promise<void>;
+    setLookupResponse(response: LookupResponse): void;
+    abort(): void;
+    clear(): void;
+    scrollToArticle(dictionaryId: string): void;
+    private renderResponse;
+    private handleFrameLoaded;
+    private readonly handleBridgeMessage;
+    private handleLookupMessage;
+    private handleMediaMessage;
+    private handleExternalLink;
+    private openExternal;
+    private updateBrand;
+    private setState;
+    private postCommand;
+    private emit;
+}
+export declare function defineGoldendictView(tagName?: string): typeof GoldenDictView;
+declare global {
+    interface HTMLElementTagNameMap {
+        "goldendict-view": GoldenDictView;
+    }
+}
+//# sourceMappingURL=goldendict-view.d.ts.map

package/dist/element/goldendict-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goldendict-view.d.ts","sourceRoot":"","sources":["../../src/element/goldendict-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EAGV,uBAAuB,EAEvB,eAAe,EAEf,cAAc,EAEd,YAAY,EACZ,SAAS,EAEV,MAAM,UAAU,CAAC;AAsClB,qBAAa,cAAe,SAAQ,WAAW;IAC7C,MAAM,CAAC,QAAQ,CAAC,kBAAkB,WAMhC;IAEF,QAAQ,CAAC,UAAU,SAAoB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,iBAAiB,CAAC,CAAkB;IAC5C,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,aAAa,CAAC,CAAiB;IACvC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,kBAAkB,CAAgB;IAC1C,OAAO,CAAC,aAAa,CAAC,CAAS;;IAyB/B,iBAAiB,IAAI,IAAI;IAQzB,oBAAoB,IAAI,IAAI;IAK5B,wBAAwB,CACtB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI;IAuBP,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,EAExB;IAED,IAAI,MAAM,IAAI,gBAAgB,CAE7B;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAEjC;IAED,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,eAAe,EAM/B;IAED,IAAI,YAAY,IAAI,YAAY,CAI/B;IAED,IAAI,YAAY,CAAC,KAAK,EAAE,YAAY,EAEnC;IAED,IAAI,aAAa,IAAI,SAAS,MAAM,EAAE,CAErC;IAED,IAAI,aAAa,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAEzC;IAED,IAAI,KAAK,IAAI,SAAS,CAErB;IAED,IAAI,QAAQ,IAAI,cAAc,GAAG,SAAS,CAEzC;IAED,eAAe,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI;IAIjD,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,aAAa,GAAE,SAAS,MAAM,EAA4B,GACzD,OAAO,CAAC,IAAI,CAAC;IAqChB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAKjD,KAAK,IAAI,IAAI;IAKb,KAAK,IAAI,IAAI;IASb,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAI3C,OAAO,CAAC,cAAc;IAetB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CA6ClC;IAEF,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,kBAAkB;IA0B1B,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,QAAQ;IAiChB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,IAAI;CAcb;AAED,wBAAgB,oBAAoB,CAClC,OAAO,SAAoB,GAC1B,OAAO,cAAc,CAUvB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,iBAAiB,EAAE,cAAc,CAAC;KACnC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { DictionaryApiError, DictionaryClient } from "./client/dictionary-client";
+export { GoldenDictView, defineGoldendictView, } from "./element/goldendict-view";
+export { GOLDENDICT_SCHEME_SUPPORT, classifyArticleLink, resolveResourceUrl, type ArticleLinkAction, type ResourceContext, } from "./renderer/link-router";
+export { DARK_THEME_TOKENS, LIGHT_THEME_TOKENS, escapeStyleText, resolveThemeMode, themeToCss, } from "./renderer/theme";
+export { GOLDENDICT_EVENTS } from "./types";
+export type * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EACL,cAAc,EACd,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,mBAAmB,SAAS,CAAC"}