@lensmap/astro-loader 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lensmap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @lensmap/astro-loader
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental `.lensmap` content collections for **Astro 7.4.0**. This release deliberately uses Astro's private `addContentEntryType` / `getRenderModule` seam and checks that exact version. It is not a stable Astro extension API. Node >=24.16 is required.
+
+```sh
+pnpm add @lensmap/astro-loader @lensmap/document astro@7.4.0
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import lensmap from "@lensmap/astro-loader";
+export default defineConfig({ integrations: [lensmap()] });
+```
+
+```ts
+// src/content.config.ts
+import { defineCollection, z } from "astro:content";
+import { lensmapLoader } from "@lensmap/astro-loader";
+export const collections = {
+  maps: defineCollection({
+    loader: lensmapLoader({ base: "./src/maps" }),
+    schema: z.object({
+      title: z.string(),
+      category: z.string().default("Notes"),
+    }),
+  }),
+};
+```
+
+```yaml
+version: v1
+frontmatter:
+  title: An expedition
+nodes:
+  - summary: Arrival
+    full_text: |
+      # Arrival
+
+      The complete authored Markdown stays intact.
+```
+
+One source file becomes one native collection entry. `lensmapLoader()` is a small native `glob()` composition; it accepts `base`, `generateId`, `retainBody`, `deferRender` and an optional `pattern` (default `**/*.lensmap`). For mixed collections use `pattern: '**/*.{md,mdx,lensmap}'` or Astro's own `glob()`.
+
+## Rendering in plain Astro
+
+Use native `getCollection()` / `getEntry()` and `render()` from `astro:content`, then **pass the actual entry**:
+
+```astro
+---
+import { getEntry, render } from 'astro:content';
+const entry = await getEntry('maps', 'expedition');
+if (!entry) throw new Error('Missing expedition');
+const { Content } = await render(entry);
+---
+<Content entry={entry} />
+```
+
+The default component renders the full thought article on the server, without an extra outer heading or disclosure. It does not provide an interactive viewer and has no React or Starlight dependency.
+
+The native document engine validates the **original source**, including its optional open-ended `frontmatter`; no frontmatter stripping or YAML reserialization occurs. Authored metadata remains separate from schema-transformed/defaulted `entry.data`. The effective entry keeps native `id` and `filePath`. Whole entries, source frontmatter and request contexts are never automatically serialized into client props.
+
+## Markdown is inert by default
+
+Thoughts use the consuming site's configured Markdown processor, followed by HTML sanitization. MDX expressions and imports do not execute on this path. Relative Markdown images are imported from the original map directory as inert asset URLs (the supported local image formats are AVIF, GIF, JPEG, PNG, SVG, TIFF and WebP). Host Markdown transformations run first; executable scripts/handlers and unsafe HTML are then removed. Relative hyperlinks retain authored spelling, just like native Markdown; they are not automatically graph connections. This adapter does not provide Astro image optimization for inert Markdown images.
+
+## Explicit build-time MDX admission
+
+Install and configure **@astrojs/mdx 8.1.0**, then admit exact local files in Astro integration options:
+
+```js
+import mdx from "@astrojs/mdx";
+import { fileURLToPath } from "node:url";
+// alongside the other imports above
+export default defineConfig({
+  integrations: [
+    mdx(),
+    lensmap({
+      mdx: {
+        admittedSources: [
+          fileURLToPath(
+            new URL("./src/maps/expedition.lensmap", import.meta.url),
+          ),
+        ],
+      },
+    }),
+  ],
+});
+```
+
+Both host MDX capability and canonical local-file admission are required. A missing configured host MDX integration is an error. Other local maps remain inert even on the same origin. Fetched sources and precompiled output never grant admission; there is no runtime MDX compiler or remote-source execution API. Source options belong in Astro configuration, **not** portable Lensmap YAML.
+
+Admitted thoughts compile through the actual host MDX integration as virtual sibling modules of the source map: relative imports and assets resolve beside the authored `.lensmap`, not in a generated cache directory. MDX receives `props.entry` (including effective `data`, `id`, `filePath`) and separate `props.authoredFrontmatter`. Expressions such as `{props.entry.data.title}` run on the build server. Source admission is **not an import/process sandbox**. MDX diagnostics identify the virtual sibling thought module; this adapter does not remap compiler diagnostics back to YAML line positions. Only admit source controlled and reviewed by the host. Hydrated components and pre-rendered HTML are not evidence of trust. Compiled client islands require the host's own renderer/capability setup and remain ordinary Astro islands; this package does not hydrate arbitrary selected HTML snapshots.
+
+## Custom content composition
+
+`lensmap({ contentComponent })` accepts a resolvable Astro component module specifier or an absolute component path. A custom component receives `graph` (the engine's semantic graph), `authoredFrontmatter`, `executable` and forwarded `<Content>` props. Each thought has a named callback slot keyed by `node.key`; render it with `String(await Astro.slots.render(node.key, [entry]) ?? '')`. The callback receives the host-selected effective entry. This is how the thin Starlight layer shares compilation without making this package depend on Starlight. Only serialize deliberately chosen public graph/rendered content into an island, never arbitrary server metadata.
+
+Generated wrapper names include a source-path hash (no same-basename collisions); identical content is not rewritten, avoiding unnecessary HMR churn. Generated wrappers live below the host's Astro `cacheDir`; authored source files are not changed.
+
+## Development evidence
+
+From the Lensmap workspace, after dependencies and `@lensmap/document` are built:
+
+```sh
+pnpm --filter @lensmap/astro-loader build
+pnpm --filter @lensmap/astro-loader test
+pnpm --filter @lensmap/astro-loader typecheck
+```
+
+The native synthetic consumer proves effective/raw metadata separation, entry-aware callback slots, relative MDX component/SVG imports, inert local image resolution, site smart punctuation, same-basename isolation, sanitization and unchanged generated-file mtimes across repeated builds. `test/site` is synthetic test source and is not shipped. Compatibility is qualified only for the exact peers above; no broad Astro-version or full client-island lifecycle guarantee is made.

package/dist/adapter.d.ts

@@ -0,0 +1,25 @@
+import { type SemanticGraph } from "@lensmap/document";
+export interface ExecutionOptions {
+    /** Exact local files, compared after realpath. Admission is not sandboxing. */
+    mdx?: {
+        admittedSources: readonly string[];
+    };
+}
+export type Source = {
+    kind: "local";
+    path: string;
+} | {
+    kind: "fetched";
+    url: string;
+} | {
+    kind: "compiled";
+};
+export declare function canExecute(source: Source, options: ExecutionOptions, installed: boolean): boolean;
+export interface ParsedMap {
+    source: string;
+    authoredFrontmatter: Record<string, unknown>;
+    graph: SemanticGraph;
+}
+export declare function parseMap(source: string, uri: string): ParsedMap;
+export declare function moduleStem(path: string): string;
+export declare function writeGenerated(path: string, content: string): boolean;

package/dist/components/Content.astro

@@ -0,0 +1,20 @@
+---
+import type { SemanticGraph } from "@lensmap/document";
+
+interface Props {
+  graph: SemanticGraph;
+  entry?: unknown;
+  authoredFrontmatter: Record<string, unknown>;
+  executable: boolean;
+}
+const { graph, entry } = Astro.props;
+const rendered = await Promise.all(
+  graph.nodes.map(async (node) => ({
+    node,
+    html: await Astro.slots.render(node.key, [entry]),
+  })),
+);
+---
+<section data-static-thoughts>
+  {rendered.map(({ node, html }) => <section data-thought={node.key}><h2>{node.title}</h2><div set:html={html} /></section>)}
+</section>

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { AstroIntegration } from "astro";
+import { glob } from "astro/loaders";
+import { type ExecutionOptions } from "./adapter.js";
+export type { ExecutionOptions, ParsedMap, Source } from "./adapter.js";
+export { canExecute, parseMap } from "./adapter.js";
+export interface LensmapOptions extends ExecutionOptions {
+    /** An Astro component module. Receives graph, authoredFrontmatter and callback thought slots. */
+    contentComponent?: string;
+}
+/** Compose with native Astro collection schemas. Entry data is only authored frontmatter. */
+export declare function lensmapLoader(options?: Omit<Parameters<typeof glob>[0], "pattern"> & {
+    pattern?: string | string[];
+}): import("astro/loaders").Loader;
+/** Experimental private content-entry seam, deliberately limited to Astro 7.4.0. */
+export default function lensmap(options?: LensmapOptions): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,253 @@
+// src/index.ts
+import { mkdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { glob } from "astro/loaders";
+
+// src/adapter.ts
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import {
+  DocumentSchema,
+  DocumentSession
+} from "@lensmap/document";
+import { parseDocument } from "yaml";
+function canExecute(source, options, installed) {
+  if (!installed || !options.mdx || source.kind !== "local") return false;
+  try {
+    const path = realpathSync(source.path);
+    return options.mdx.admittedSources.some((admitted) => {
+      try {
+        return realpathSync(admitted) === path;
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+function parseMap(source, uri) {
+  const snapshot = new DocumentSession(uri, source).snapshot();
+  if (!snapshot.valid || !snapshot.graph)
+    throw new Error(
+      `Invalid Lensmap ${uri}: ${JSON.stringify(snapshot.diagnostics)}`
+    );
+  const raw = DocumentSchema.parse(parseDocument(source).toJS());
+  return {
+    source,
+    authoredFrontmatter: raw.frontmatter ?? {},
+    graph: snapshot.graph
+  };
+}
+function moduleStem(path) {
+  return createHash("sha256").update(path).digest("hex");
+}
+function writeGenerated(path, content) {
+  if (existsSync(path) && readFileSync(path, "utf8") === content) return false;
+  writeFileSync(path, content);
+  return true;
+}
+
+// src/markdown.ts
+import { fileURLToPath } from "node:url";
+import rehypeParse from "rehype-parse";
+import rehypeSanitize from "rehype-sanitize";
+import rehypeStringify from "rehype-stringify";
+import { unified } from "unified";
+async function sanitizeMarkdown(code, fileUrl, identity) {
+  const processor = unified().use(rehypeParse, { fragment: true }).use(rehypeSanitize).use(rehypeStringify);
+  const tree = processor.parse(code);
+  const assets = [];
+  function visit(node) {
+    if (!node || typeof node !== "object") return;
+    const element = node;
+    if (element.tagName === "img" && element.properties) {
+      const properties = element.properties;
+      const marker = Object.entries(properties).find(
+        ([key]) => key.toLowerCase() === "__astro_image_"
+      );
+      if (marker && typeof marker[1] === "string") {
+        const restored = JSON.parse(marker[1]);
+        if (restored && typeof restored === "object")
+          Object.assign(properties, restored);
+        delete properties[marker[0]];
+      }
+      const src = properties.src;
+      if (typeof src === "string" && !/^(?:[a-z][a-z\d+.-]*:|\/|#)/i.test(src)) {
+        const url = new URL(src, fileUrl);
+        if (!/\.(?:avif|gif|jpe?g|png|svg|tiff?|webp)$/i.test(url.pathname))
+          throw new Error(`Unsupported local Markdown image: ${src}`);
+        const token = `__LENSMAP_ASSET_${identity}_${assets.length}__`;
+        assets.push({ path: fileURLToPath(url), token });
+        properties.src = token;
+      }
+    }
+    element.children?.forEach(visit);
+  }
+  visit(tree);
+  return { html: processor.stringify(await processor.run(tree)), assets };
+}
+
+// src/index.ts
+function lensmapLoader(options = {}) {
+  return glob({ ...options, pattern: options.pattern ?? "**/*.lensmap" });
+}
+var quote = JSON.stringify;
+function lensmap(options = {}) {
+  let config;
+  let renderer;
+  let installedMdx = false;
+  const mdxModules = /* @__PURE__ */ new Map();
+  return {
+    name: "@lensmap/astro-loader",
+    hooks: {
+      "astro:config:setup": (setup) => {
+        const version = JSON.parse(
+          readFileSync2(
+            new URL(import.meta.resolve("astro/package.json")),
+            "utf8"
+          )
+        ).version;
+        if (version !== "7.4.0")
+          throw new Error(
+            `Lensmap experimental content seam requires Astro 7.4.0; received ${version}`
+          );
+        const add = setup.addContentEntryType;
+        if (typeof add !== "function")
+          throw new Error(
+            "Lensmap requires Astro 7.4.0 private addContentEntryType support"
+          );
+        setup.updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "lensmap-source-relative-mdx",
+                enforce: "pre",
+                resolveId(id) {
+                  if (mdxModules.has(id)) return id;
+                },
+                load(id) {
+                  const module = mdxModules.get(id.split("?")[0] ?? id);
+                  if (!module) return;
+                  this.addWatchFile(module.source);
+                  return module.code;
+                }
+              }
+            ]
+          }
+        });
+        add({
+          extensions: [".lensmap"],
+          handlePropagation: true,
+          contentModuleTypes: "declare module 'astro:content' { interface Render { '.lensmap': Promise<RenderResult>; } }",
+          getEntryInfo({ contents, fileUrl }) {
+            const { authoredFrontmatter: data, graph } = parseMap(
+              contents,
+              fileUrl.href
+            );
+            return {
+              data,
+              body: graph.nodes.map((node) => node.markdown).join("\n\n"),
+              rawData: quote(data),
+              slug: typeof data.slug === "string" ? data.slug : void 0
+            };
+          },
+          async getRenderModule({ contents, fileUrl }) {
+            const path = fileURLToPath2(fileUrl);
+            const { graph, authoredFrontmatter } = parseMap(
+              contents,
+              fileUrl.href
+            );
+            const executable = canExecute(
+              { kind: "local", path },
+              options,
+              installedMdx
+            );
+            const generated = fileURLToPath2(
+              new URL("lensmap/", config.cacheDir)
+            );
+            mkdirSync(generated, { recursive: true });
+            const imports = [];
+            const slots = [];
+            for (const [index, node] of graph.nodes.entries()) {
+              if (executable) {
+                const id = `${path}.__lensmap_${index}.mdx`;
+                mdxModules.set(id, { code: node.markdown, source: path });
+                imports.push(`import Thought${index} from ${quote(id)};`);
+                slots.push(
+                  `<fragment slot=${quote(node.key)}>{(entry) => <Thought${index} entry={entry} authoredFrontmatter={authoredFrontmatter} />}</fragment>`
+                );
+              } else {
+                renderer ??= await config.markdown.processor.createRenderer({
+                  ...config.markdown,
+                  image: config.image
+                });
+                const rendered = await renderer.render(node.markdown, {
+                  fileURL: fileUrl
+                });
+                const { html, assets } = await sanitizeMarkdown(
+                  rendered.code,
+                  fileUrl,
+                  `${moduleStem(path)}_${index}`
+                );
+                let expression = quote(html);
+                for (const [assetIndex, asset] of assets.entries()) {
+                  const name = `Asset${index}_${assetIndex}`;
+                  imports.push(
+                    `import ${name} from ${quote(`${asset.path}?url`)};`
+                  );
+                  expression += `.replaceAll(${quote(asset.token)}, ${name})`;
+                }
+                slots.push(
+                  `<Fragment slot=${quote(node.key)} set:html={${expression}} />`
+                );
+              }
+            }
+            const component = options.contentComponent ?? fileURLToPath2(
+              new URL("./components/Content.astro", import.meta.url)
+            );
+            const wrapper = resolve(generated, `${moduleStem(path)}.astro`);
+            writeGenerated(
+              wrapper,
+              `---
+import MapContent from ${quote(component)};
+${imports.join("\n")}
+const graph = ${quote(graph)};
+const authoredFrontmatter = ${quote(authoredFrontmatter)};
+---
+<MapContent {...Astro.props} graph={graph} authoredFrontmatter={authoredFrontmatter} executable={${executable}}>
+${slots.join("\n")}
+</MapContent>
+`
+            );
+            return {
+              code: `export { default as Content } from ${quote(wrapper)}; export const getHeadings = () => [];`,
+              map: null
+            };
+          }
+        });
+      },
+      "astro:config:done": ({ config: resolved }) => {
+        config = resolved;
+        installedMdx = resolved.integrations.some(
+          (integration) => integration.name === "@astrojs/mdx"
+        );
+        if (!config.markdown.processor?.createRenderer)
+          throw new Error(
+            "Lensmap requires the Astro 7.4.0 Markdown processor API"
+          );
+        if (options.mdx && !installedMdx)
+          throw new Error(
+            "Lensmap MDX admission requires the host @astrojs/mdx integration"
+          );
+      }
+    }
+  };
+}
+export {
+  canExecute,
+  lensmap as default,
+  lensmapLoader,
+  parseMap
+};

package/dist/markdown.d.ts

@@ -0,0 +1,8 @@
+/** Restore Astro's inert image markers before sanitizing, importing local files as URLs only. */
+export declare function sanitizeMarkdown(code: string, fileUrl: URL, identity: string): Promise<{
+    html: string;
+    assets: {
+        path: string;
+        token: string;
+    }[];
+}>;

package/package.json

@@ -1,6 +1,60 @@
 {
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24.16.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest",
+    "registry": "https://registry.npmjs.org/"
+  },
   "name": "@lensmap/astro-loader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Experimental portable Lensmap Astro content integration",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicodoggie/lensmap.git",
+    "directory": "packages/astro-loader"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./components/*": "./dist/components/*"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "@lensmap/document": "workspace:*",
+    "rehype-parse": "9.0.1",
+    "rehype-sanitize": "6.0.0",
+    "rehype-stringify": "10.0.1",
+    "unified": "11.0.5",
+    "yaml": "2.9.1"
+  },
+  "peerDependencies": {
+    "astro": "7.4.0",
+    "@astrojs/mdx": "8.1.0"
+  },
+  "devDependencies": {
+    "astro": "7.4.0",
+    "@astrojs/mdx": "8.1.0",
+    "esbuild": "0.28.2",
+    "typescript": "7.0.2",
+    "@types/node": "24.19.2"
+  },
+  "peerDependenciesMeta": {
+    "@astrojs/mdx": {
+      "optional": true
+    }
+  }
+}