@gtkx/codegen 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/codegen",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Generates typed GTK bindings and API docs from GIR and GL registries.",
   "keywords": [
     "gtkx",
@@ -58,9 +58,9 @@
     "fast-xml-parser": "^5.11.0",
     "fast-xml-validator": "^1.4.2",
     "typescript": "^6.0.3",
-    "@gtkx/cairo": "1.4.0",
-    "@gtkx/utils": "1.4.0",
-    "@gtkx/react": "1.4.0"
+    "@gtkx/react": "1.6.0",
+    "@gtkx/utils": "1.6.0",
+    "@gtkx/cairo": "1.6.0"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/analysis/descriptor-render.ts

@@ -62,6 +62,7 @@ type ArgIndexOptions = {
     argIndexMap: Map<number, number> | undefined;
     cursor: GirCursorBounds | undefined;
     hasOutIndirection: boolean;
+    isReceived: boolean;
 };
 
 type CursorArgIndexOptions = ArgIndexOptions & { cursor: GirCursorBounds };
@@ -76,11 +77,13 @@ type RenderDescriptorOptions = Partial<ArgIndexOptions> & {
 type RecordPlacement = {
     isCallerAllocated?: boolean;
     isInline?: boolean;
+    isReceived?: boolean;
 };
 
 type RecordLayout = {
     isCallerAllocated: boolean;
     isInline: boolean;
+    isReceived: boolean;
 };
 
 type FundamentalDescriptor = {
@@ -90,6 +93,7 @@ type FundamentalDescriptor = {
     typeName: string | undefined;
     ownership: Ownership;
     wrapperClass?: string | undefined;
+    fallbackClass?: string | undefined;
     isCallerAllocated?: boolean | undefined;
     isInline?: boolean | undefined;
 };
@@ -110,6 +114,7 @@ type FundamentalRecordOptions = {
     unrefFunc: string;
     ownership: Ownership;
     wrapperClass: string | undefined;
+    fallbackClass?: string | undefined;
     isCallerAllocated: boolean;
     isInline: boolean;
 };
@@ -169,6 +174,7 @@ const argIndexOptions = (options: RenderDescriptorOptions): ArgIndexOptions => (
     argIndexMap: options.argIndexMap,
     cursor: options.cursor,
     hasOutIndirection: options.hasOutIndirection === true,
+    isReceived: options.isReceived === true,
 });
 
 const renderDescriptor = (
@@ -310,7 +316,12 @@ const renderParamDescriptor = (
     ref: TypeId | undefined,
     argIndex: Partial<ArgIndexOptions> = {},
 ): string => {
-    const behindRef: RenderDescriptorOptions = { ...argIndex, cursor: parameter.cursor, hasOutIndirection: true };
+    const behindRef: RenderDescriptorOptions = {
+        ...argIndex,
+        cursor: parameter.cursor,
+        hasOutIndirection: true,
+        isReceived: true,
+    };
 
     if (isCellInout(context.library, parameter)) {
         return tRef(renderDescriptor(context, ref, parameter.transferOwnership, behindRef), true);
@@ -323,6 +334,7 @@ const renderParamDescriptor = (
     return renderDescriptor(context, ref, parameter.transferOwnership, {
         ...argIndex,
         isCallerAllocated: isCallerAllocatedOut(parameter) || isRecordInout(context, parameter),
+        isReceived: true,
     });
 };
 
@@ -394,7 +406,7 @@ const renderCallbackType = (
 
     return tCallback({
         argTypes,
-        returns: renderDescriptor(context, returnValue.type, returnValue.transferOwnership),
+        returns: renderDescriptor(context, returnValue.type, returnValue.transferOwnership, { isReceived: true }),
         options: callbackOptionsArg(owningParameter, findUserDataIndex(callback.parameters), callback.throws),
     });
 };
@@ -420,17 +432,28 @@ const primitiveExpression = (category: PrimitiveCategory, ownership: Ownership):
 };
 
 const renderFundamental = (descriptor: FundamentalDescriptor): string => {
-    const { lib, refFunc, unrefFunc, typeName, ownership, wrapperClass, isCallerAllocated, isInline } = descriptor;
+    const { lib, refFunc, unrefFunc, typeName, ownership, wrapperClass, fallbackClass } = descriptor;
 
     return tFundamental(lib, refFunc, unrefFunc, {
         ownership,
         typeName,
         wrapperClass,
-        isCallerAllocated,
-        isInline,
+        fallbackClass,
+        isCallerAllocated: descriptor.isCallerAllocated,
+        isInline: descriptor.isInline,
     });
 };
 
+const fallbackClassThunk = (
+    context: ModuleContext,
+    namespaceName: string,
+    name: string,
+    isReceived: boolean,
+): string | undefined =>
+    isReceived && context.library.isTreeShaken
+        ? `() => ${context.qualify(namespaceName, sanitizeTypeIdentifier(name))}`
+        : undefined;
+
 const sunkOwnership = (
     ancestor: AncestorFundamental,
     ownership: Ownership,
@@ -447,15 +470,20 @@ const classOrInterfaceExpression = (
     context: ModuleContext,
     resolved: Extract<EntityType, { kind: "class" | "interface" }>,
     ownership: Ownership,
-    isNewlyCreated: boolean,
+    options: { isNewlyCreated: boolean; isReceived: boolean },
 ): string => {
     const ancestor = fundamentalAncestor(context, resolved);
+    const fallbackClass = fallbackClassThunk(context, resolved.namespace.name, resolved.value.name, options.isReceived);
 
     if (ancestor === undefined) {
-        return tObject(ownership);
+        return tObject(ownership, fallbackClass);
     }
 
-    return renderFundamental({ ...ancestor, ownership: sunkOwnership(ancestor, ownership, isNewlyCreated) });
+    return renderFundamental({
+        ...ancestor,
+        ownership: sunkOwnership(ancestor, ownership, options.isNewlyCreated),
+        fallbackClass,
+    });
 };
 
 const isClassOrInterface = (type: GirType | undefined): type is Extract<EntityType, { kind: "class" | "interface" }> =>
@@ -552,6 +580,7 @@ const renderSelfDescriptor = (context: ModuleContext, instance: GirParameter): s
 const recordLayout = (placement: RecordPlacement): RecordLayout => ({
     isCallerAllocated: placement.isCallerAllocated ?? false,
     isInline: placement.isInline ?? false,
+    isReceived: placement.isReceived === true,
 });
 
 const recordRefPair = (record: ResolvedRecord): { refFunc: string | undefined; unrefFunc: string | undefined } => ({
@@ -588,7 +617,7 @@ const structExpression = (
 };
 
 const fundamentalRecordExpression = (options: FundamentalRecordOptions): string => {
-    const { resolved, lib, refFunc, unrefFunc, ownership, wrapperClass, isCallerAllocated, isInline } = options;
+    const { resolved, lib, refFunc, unrefFunc, ownership, wrapperClass, fallbackClass } = options;
 
     return renderFundamental({
         lib,
@@ -597,8 +626,9 @@ const fundamentalRecordExpression = (options: FundamentalRecordOptions): string
         typeName: resolved.value.glibTypeName,
         ownership,
         wrapperClass,
-        isCallerAllocated,
-        isInline,
+        fallbackClass,
+        isCallerAllocated: options.isCallerAllocated,
+        isInline: options.isInline,
     });
 };
 
@@ -608,6 +638,7 @@ const boxedRecordExpression = (options: {
     ownership: Ownership;
     isCallerAllocated: boolean;
     isInline: boolean;
+    isReceived: boolean;
     typeFnName: string;
 }): string => {
     const { context, resolved, ownership, isCallerAllocated, isInline, typeFnName } = options;
@@ -623,6 +654,7 @@ const boxedRecordExpression = (options: {
         isCallerAllocated,
         isInline,
         size: size > 0 ? size : undefined,
+        fallbackClass: fallbackClassThunk(context, resolved.namespace.name, record.name, options.isReceived),
     });
 };
 
@@ -653,35 +685,48 @@ const isPlainStruct = (resolved: Extract<EntityType, { kind: "record" }>): boole
     return record.glibGetType === undefined;
 };
 
-const recordExpression = (
+const fundamentalRecordPath = (
     context: ModuleContext,
     resolved: Extract<EntityType, { kind: "record" }>,
     ownership: Ownership,
-    placement: RecordPlacement = {},
-): string => {
+    placement: RecordPlacement,
+): string | undefined => {
     const record = resolved.value;
     const { refFunc, unrefFunc } = recordRefPair(record);
     const lib = resolved.namespace.sharedLibrary;
 
-    if (refFunc !== undefined && unrefFunc !== undefined && lib !== undefined) {
-        const wrapperClass = requiresFallbackClass(record)
-            ? context.qualify(resolved.namespace.name, sanitizeTypeIdentifier(record.name))
-            : undefined;
-
-        return fundamentalRecordExpression({
-            resolved,
-            lib,
-            refFunc,
-            unrefFunc,
-            ownership,
-            wrapperClass,
-            ...recordLayout(placement),
-        });
+    if (refFunc === undefined || unrefFunc === undefined || lib === undefined) {
+        return undefined;
     }
 
-    return plainRecordExpression(context, resolved, ownership, placement);
+    const wrapperClass = requiresFallbackClass(record)
+        ? context.qualify(resolved.namespace.name, sanitizeTypeIdentifier(record.name))
+        : undefined;
+
+    return fundamentalRecordExpression({
+        resolved,
+        lib,
+        refFunc,
+        unrefFunc,
+        ownership,
+        wrapperClass,
+        fallbackClass:
+            wrapperClass === undefined
+                ? fallbackClassThunk(context, resolved.namespace.name, record.name, placement.isReceived === true)
+                : undefined,
+        ...recordLayout(placement),
+    });
 };
 
+const recordExpression = (
+    context: ModuleContext,
+    resolved: Extract<EntityType, { kind: "record" }>,
+    ownership: Ownership,
+    placement: RecordPlacement = {},
+): string =>
+    fundamentalRecordPath(context, resolved, ownership, placement) ??
+    plainRecordExpression(context, resolved, ownership, placement);
+
 const rawEnumDescriptor = (isSigned: boolean): string => (isSigned ? tInt32 : tUint32);
 
 const flagsMask = (resolved: Extract<EntityType, { kind: "enum" }>): number =>
@@ -711,12 +756,16 @@ const expressionForResolved = (
     switch (resolved.kind) {
         case "class":
         case "interface": {
-            return classOrInterfaceExpression(context, resolved, ownership, options.isNewlyCreated ?? false);
+            return classOrInterfaceExpression(context, resolved, ownership, {
+                isNewlyCreated: options.isNewlyCreated ?? false,
+                isReceived: options.isReceived === true,
+            });
         }
         case "record": {
             return recordExpression(context, resolved, ownership, {
                 isCallerAllocated: options.isCallerAllocated ?? false,
                 isInline: options.isInline ?? false,
+                isReceived: options.isReceived === true,
             });
         }
         case "enum": {

package/src/analysis/descriptor.ts

@@ -1,6 +1,6 @@
 import { sourceStringLiteral } from "@gtkx/utils";
 import type { GirCursorBounds } from "../gir/parameter.js";
-import { joinArgs } from "../writer/emit.js";
+import { joinArgs, pure } from "../writer/emit.js";
 
 type Ownership = "borrowed" | "full";
 
@@ -70,6 +70,7 @@ type BoxedOptions = {
     isCallerAllocated: boolean;
     isInline?: boolean;
     size: number | undefined;
+    fallbackClass?: string | undefined;
 };
 
 type StructOptions = {
@@ -83,6 +84,7 @@ type FundamentalOptions = {
     ownership: Ownership;
     typeName: string | undefined;
     wrapperClass: string | undefined;
+    fallbackClass?: string | undefined;
     isCallerAllocated?: boolean | undefined;
     isInline?: boolean | undefined;
 };
@@ -178,26 +180,29 @@ const optionsObject = (parts: (string | undefined)[]): string | undefined => {
     return present.length === 0 ? undefined : `{ ${present.join(", ")} }`;
 };
 
+const optionalLiteralEntry = (key: string, value: string | undefined): string | undefined =>
+    value === undefined ? undefined : `${key}: ${sourceStringLiteral(value)}`;
+
 const tScalar = (name: ScalarDescriptorName): string => T[name];
 
 const tString = (ownership: Ownership, length?: string): string =>
     call("string", [sourceStringLiteral(ownership), length]);
 
-const tObject = (ownership: Ownership): string => call("object", [sourceStringLiteral(ownership)]);
+const tObject = (ownership: Ownership, fallbackClass?: string): string =>
+    call("object", [sourceStringLiteral(ownership), fallbackClass]);
 
 const tBoxed = (glibName: string, options: BoxedOptions): string =>
     call("boxed", [
         sourceStringLiteral(glibName),
         optionsObject([
             `ownership: ${sourceStringLiteral(options.ownership)}`,
-            options.sharedLibrary === undefined
-                ? undefined
-                : `sharedLibrary: ${sourceStringLiteral(options.sharedLibrary)}`,
+            optionalLiteralEntry("sharedLibrary", options.sharedLibrary),
             `getTypeFnName: ${sourceStringLiteral(options.getTypeFnName)}`,
-            options.freeFnName === undefined ? undefined : `freeFnName: ${sourceStringLiteral(options.freeFnName)}`,
+            optionalLiteralEntry("freeFnName", options.freeFnName),
             options.isCallerAllocated ? "isCallerAllocated: true" : undefined,
             options.isInline === true ? "isInline: true" : undefined,
             options.size === undefined ? undefined : `size: ${String(options.size)}`,
+            options.fallbackClass === undefined ? undefined : `fallbackClass: ${options.fallbackClass}`,
         ]),
     ]);
 
@@ -224,6 +229,7 @@ const tFundamental = (lib: string, refFunc: string, unrefFunc: string, options:
             `ownership: ${sourceStringLiteral(options.ownership)}`,
             options.typeName === undefined ? undefined : `typeName: ${sourceStringLiteral(options.typeName)}`,
             options.wrapperClass === undefined ? undefined : `wrapperClass: ${options.wrapperClass}`,
+            options.fallbackClass === undefined ? undefined : `fallbackClass: ${options.fallbackClass}`,
             options.isCallerAllocated === true ? "isCallerAllocated: true" : undefined,
             options.isInline === true ? "isInline: true" : undefined,
         ]),
@@ -327,11 +333,13 @@ const tFn = (lib: string, cIdentifier: string, spec: FnSpecParts): string => {
     const unpackEntry = spec.isReturnUnpacked ? `, ${UNPACKED_RETURN_ENTRY}` : "";
     const throwsEntry = spec.canThrow ? ", canThrow: true" : "";
 
-    return call("fn", [
-        sourceStringLiteral(lib),
-        sourceStringLiteral(cIdentifier),
-        `{ args: ${spec.args}, returns: ${spec.returns}${skipEntry}${unpackEntry}${throwsEntry} }`,
-    ]);
+    return pure(
+        call("fn", [
+            sourceStringLiteral(lib),
+            sourceStringLiteral(cIdentifier),
+            `() => ({ args: ${spec.args}, returns: ${spec.returns}${skipEntry}${unpackEntry}${throwsEntry} })`,
+        ]),
+    );
 };
 
 export {

package/src/compile.ts

@@ -76,9 +76,12 @@ const DECLARATION_EMIT = {
 };
 
 const MODULE_EMIT = {
-    removeComments: true,
+    removeComments: false,
 };
 
+const PURE_ANNOTATION_TEXT = "@__PURE__";
+const PURE_ANNOTATION_COMMENT = ` ${PURE_ANNOTATION_TEXT} `;
+
 const DECLARATION_OPTIONS = ts.convertCompilerOptionsFromJson(
     { ...BASE_COMPILER_OPTIONS, ...DECLARATION_EMIT },
     ".",
@@ -213,7 +216,7 @@ const diagnosticError = (params: ProjectContext, diagnostics: ts.Diagnostic[]):
 
     const lines = [...diagnosed.map((entry) => entry.text), ...originLines(diagnosed, params.files)];
 
-    return new Error(`Compiling ${label} found ${String(diagnosed.length)} error(s):\n${lines.join("\n")}`);
+    return new Error(`Compiling ${label} failed:\n${lines.join("\n")}`);
 };
 
 const keepFailedProject = (input: FailedProjectInput): Error => {
@@ -266,10 +269,46 @@ const transpileOptions = (compilerOptions: ts.CompilerOptions, fileName: string)
     reportDiagnostics: true,
 });
 
+const isPureAnnotated = (text: string, node: ts.Node): boolean =>
+    ts.isCallExpression(node) &&
+    node.pos >= 0 &&
+    (ts.getLeadingCommentRanges(text, node.pos) ?? []).some((range) =>
+        text.slice(range.pos, range.end).includes(PURE_ANNOTATION_TEXT),
+    );
+
+const dropCommentsExceptPureAnnotations =
+    (): ts.TransformerFactory<ts.SourceFile> => (context) => (sourceFile) => {
+        const { text } = sourceFile;
+
+        const visit = (node: ts.Node): ts.Node => {
+            const isPure = isPureAnnotated(text, node);
+            const visited = ts.visitEachChild(node, visit, context);
+            ts.setEmitFlags(visited, ts.EmitFlags.NoLeadingComments | ts.EmitFlags.NoTrailingComments);
+
+            if (isPure) {
+                ts.addSyntheticLeadingComment(
+                    visited,
+                    ts.SyntaxKind.MultiLineCommentTrivia,
+                    PURE_ANNOTATION_COMMENT,
+                    false,
+                );
+            }
+
+            return visited;
+        };
+
+        return ts.visitEachChild(sourceFile, visit, context);
+    };
+
 const emitModule = (module: SourceModule, projectDir: string): ts.Diagnostic[] => {
     const fileName = join(projectDir, module.fileName);
     const declaration = ts.transpileDeclaration(module.source, transpileOptions(DECLARATION_OPTIONS, fileName));
-    const javascript = ts.transpileModule(module.source, transpileOptions(MODULE_OPTIONS, fileName));
+
+    const javascript = ts.transpileModule(module.source, {
+        ...transpileOptions(MODULE_OPTIONS, fileName),
+        transformers: { after: [dropCommentsExceptPureAnnotations()] },
+    });
+
     const diagnostics = [...declaration.diagnostics ?? [], ...javascript.diagnostics ?? []];
 
     if (diagnostics.length > 0) {

package/src/docs/api-reference.ts

@@ -33,6 +33,8 @@ type ApiReferenceOptions = {
     isFinishTrimmed?: boolean;
     /** Describes a handle-passing inout parameter as mutated in place rather than returned; off by default. */
     isInoutInPlace?: boolean;
+    /** Folds registrations into each class so bundlers can drop unused ones; off by default. */
+    isTreeShaken?: boolean;
 };
 
 /** Narrows an `ApiReference.symbols` enumeration. */
@@ -386,6 +388,7 @@ class ApiReference {
             isValueUnwrapped: options.isValueUnwrapped === true,
             isFinishTrimmed: options.isFinishTrimmed === true,
             isInoutInPlace: options.isInoutInPlace === true,
+            isTreeShaken: options.isTreeShaken === true,
         });
 
         this.elementContext = { library: this.library, linkFor: (): string | undefined => undefined };
@@ -679,7 +682,7 @@ class ApiReference {
 
             lines.push(
                 "",
-                `## ${KIND_SECTION_TITLES[kind]} (${String(names.length)})`,
+                `## ${KIND_SECTION_TITLES[kind]}`,
                 "",
                 sortStrings(names)
                     .map((symbolName) => `\`${symbolName}\``)

package/src/docs/pipeline.ts

@@ -30,11 +30,14 @@ type DocsNamespace = {
     elements: DocsElementLink[];
 };
 
+type DocsLinkStyle = "url" | "file";
+
 type DocsOptions = {
     libraries: string[];
     girPath: string[];
     outDir: string;
     basePath?: string;
+    linkStyle?: DocsLinkStyle;
     props?: ElementProps;
     omittedProps?: OmittedProps;
     isForced?: boolean;
@@ -42,6 +45,7 @@ type DocsOptions = {
     isValueUnwrapped?: boolean;
     isFinishTrimmed?: boolean;
     isInoutInPlace?: boolean;
+    isTreeShaken?: boolean;
 };
 
 type DocsManifest = {
@@ -75,9 +79,7 @@ const namespaceIndexPage = (namespace: DocsNamespace, elements: GlibNamedClass[]
         return `| [${entry.glibName}](${link}) | ${description} |`;
     });
 
-    const description =
-        `Reference pages for the ${String(namespace.elements.length)} JSX elements in ` +
-        `the ${namespace.name} namespace.`;
+    const description = `Reference pages for the JSX elements in the ${namespace.name} namespace.`;
 
     return [
         "---",
@@ -96,7 +98,41 @@ const namespaceIndexPage = (namespace: DocsNamespace, elements: GlibNamedClass[]
     ].join("\n");
 };
 
-const rootIndexPage = (namespaces: DocsNamespace[], libraries: string[]): string => {
+const fileIndexPage = (namespaces: DocsNamespace[], libraries: string[]): string => {
+    const rows = namespaces.map(
+        (ns) => `| ${ns.name} | \`@gtkx/jsx/${ns.directory}\` | ${String(ns.elements.length)} | ${ns.link} |`,
+    );
+
+    const librariesList = libraries.map((library) => `\`${library}\``).join(", ");
+
+    return [
+        "# Element reference",
+        "",
+        `Every JSX element generated from ${librariesList} by \`gtkx codegen\` has a page here, regenerated ` +
+        "whenever the GIR libraries or the project's element configuration change. These pages describe " +
+        "this project's bindings exactly, so they are the authority on props, signals, and method signatures.",
+        "",
+        "Every path here is from the project root, ready to read as-is.",
+        "",
+        "One page per element, at `<namespace>/<element>.md`, where the element file name is its class name in " +
+        "kebab-case without the namespace prefix: `GtkButton` is `gtk/button.md`, `AdwHeaderBar` is " +
+        "`adw/header-bar.md`. Read a page directly by that path rather than searching for it.",
+        "",
+        "Each page lists the element's props (GObject properties plus what GTKX adds, with types and defaults), " +
+        "its signals as `on<Signal>` handler props with exact signatures, and the methods reachable through `ref`.",
+        "",
+        "| Namespace | Import | Elements | Index |",
+        "| --- | --- | --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+};
+
+const rootIndexPage = (namespaces: DocsNamespace[], libraries: string[], linkStyle: DocsLinkStyle): string => {
+    if (linkStyle === "file") {
+        return fileIndexPage(namespaces, libraries);
+    }
+
     const rows = namespaces.map(
         (ns) => `| [${ns.name}](${ns.link}) | \`@gtkx/jsx/${ns.directory}\` | ${String(ns.elements.length)} |`,
     );
@@ -143,12 +179,17 @@ const groupElementsByNamespace = (elements: GlibNamedClass[]): Map<string, GlibN
     return byNamespace;
 };
 
-const buildElementLinks = (elements: GlibNamedClass[], basePath: string): Map<string, string> => {
+const buildElementLinks = (
+    elements: GlibNamedClass[],
+    basePath: string,
+    linkStyle: DocsLinkStyle,
+): Map<string, string> => {
     const linkByGlibName: Map<string, string> = new Map();
+    const suffix = linkStyle === "file" ? ".md" : "";
 
     for (const entry of elements) {
         const directory = namespaceDirectory(entry.namespace);
-        const link = `${basePath}/${directory}/${elementSlug(entry.klass.name)}`;
+        const link = `${basePath}/${directory}/${elementSlug(entry.klass.name)}${suffix}`;
 
         if (linkByGlibName.values().some((existing) => existing === link)) {
             throw new Error(`Docs page slug collision for ${entry.glibName} at ${link}`);
@@ -186,16 +227,17 @@ const namespacePages = (input: {
     name: string;
     elements: GlibNamedClass[];
     basePath: string;
+    linkStyle: DocsLinkStyle;
     linkByGlibName: Map<string, string>;
     pageContext: ElementPageContext;
 }): NamespacePages => {
-    const { name, elements, basePath, linkByGlibName, pageContext } = input;
+    const { name, elements, basePath, linkStyle, linkByGlibName, pageContext } = input;
     const directory = ownedEntry(namespaceDirectory({ name }), `the GIR namespace ${name}`);
 
     const docs: DocsNamespace = {
         name,
         directory,
-        link: `${basePath}/${directory}/`,
+        link: linkStyle === "file" ? `${basePath}/${directory}/index.md` : `${basePath}/${directory}/`,
         elements: elements.map((entry) => ({ text: entry.glibName, link: linkByGlibName.get(entry.glibName) ?? "" })),
     };
 
@@ -209,10 +251,15 @@ const namespacePages = (input: {
     return { docs, pages };
 };
 
-const generatePages = (options: DocsOptions, basePath: string, library: Library): GeneratedDocs => {
+const generatePages = (
+    options: DocsOptions,
+    basePath: string,
+    linkStyle: DocsLinkStyle,
+    library: Library,
+): GeneratedDocs => {
     const intrinsicElements = collectIntrinsicElementClasses(library);
     const byNamespace = groupElementsByNamespace(intrinsicElements);
-    const linkByGlibName = buildElementLinks(intrinsicElements, basePath);
+    const linkByGlibName = buildElementLinks(intrinsicElements, basePath, linkStyle);
     const pageContext: ElementPageContext = { library, linkFor: (glibName) => linkByGlibName.get(glibName) };
     const pages: Page[] = [];
     const namespaces: DocsNamespace[] = [];
@@ -220,12 +267,12 @@ const generatePages = (options: DocsOptions, basePath: string, library: Library)
 
     for (const name of orderedNames) {
         const elements = sortStringsBy(byNamespace.get(name) ?? [], (entry) => entry.glibName);
-        const result = namespacePages({ name, elements, basePath, linkByGlibName, pageContext });
+        const result = namespacePages({ name, elements, basePath, linkStyle, linkByGlibName, pageContext });
         pages.push(...result.pages);
         namespaces.push(result.docs);
     }
 
-    pages.push({ path: ROOT_INDEX_FILENAME, content: rootIndexPage(namespaces, options.libraries) });
+    pages.push({ path: ROOT_INDEX_FILENAME, content: rootIndexPage(namespaces, options.libraries, linkStyle) });
 
     return { pages, namespaces };
 };
@@ -267,6 +314,7 @@ const giInputs = (options: DocsOptions, girFiles: string[]): GiInputs => ({
     isValueUnwrapped: options.isValueUnwrapped === true,
     isFinishTrimmed: options.isFinishTrimmed === true,
     isInoutInPlace: options.isInoutInPlace === true,
+    isTreeShaken: options.isTreeShaken === true,
 });
 
 const assertOwnedOutDir = (options: DocsOptions, manifest: DocsManifest | undefined): void => {
@@ -334,11 +382,13 @@ const writePages = (outDir: string, pages: Page[]): void => {
 
 const docsFingerprintInput = (options: DocsOptions): DocsFingerprintInput => ({
     basePath: options.basePath ?? DEFAULT_BASE_PATH,
+    linkStyle: options.linkStyle ?? "url",
     props: options.props ?? {},
     omittedProps: options.omittedProps ?? {},
 });
 
 const writeDocs = (options: DocsOptions): DocsResult => {
+    const linkStyle = options.linkStyle ?? "url";
     const input = docsFingerprintInput(options);
     setElementProps(input.props);
     setOmittedProps(input.omittedProps);
@@ -357,9 +407,10 @@ const writeDocs = (options: DocsOptions): DocsResult => {
         isValueUnwrapped: options.isValueUnwrapped === true,
         isFinishTrimmed: options.isFinishTrimmed === true,
         isInoutInPlace: options.isInoutInPlace === true,
+        isTreeShaken: options.isTreeShaken === true,
     });
 
-    const { pages, namespaces } = generatePages(options, input.basePath, library);
+    const { pages, namespaces } = generatePages(options, input.basePath, linkStyle, library);
     clearOutDir(options, previous);
     mkdirSync(options.outDir, { recursive: true });
     const manifest: DocsManifest = { generator: MANIFEST_GENERATOR, namespaces };