add read-only Java package catalog and XLIL guide

6 files changed, 540 insertions, 3 deletions

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index e2b1dd6..c8925a7 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -9,7 +9,8 @@
       "version": "0.1.0",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
-        "astro": "7.1.3"
+        "astro": "7.1.3",
+        "marked": "18.0.7"
       },
       "devDependencies": {
         "@astrojs/check": "0.9.9",
@@ -3632,6 +3633,18 @@
         "source-map-js": "^1.2.1"
       }
     },
+    "node_modules/marked": {
+      "version": "18.0.7",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-18.0.7.tgz",
+      "integrity": "sha512-iDVQ5ldaiKXn6b2JroX5kgRfmwgqolW7NpaEzTl1k/2Zh1njIEN9yniyLV/mOvWwtsE8OGgkjsCYvijuPk1dtA==",
+      "license": "MIT",
+      "bin": {
+        "marked": "bin/marked.js"
+      },
+      "engines": {
+        "node": ">= 20"
+      }
+    },
     "node_modules/mdast-util-to-hast": {
       "version": "13.2.1",
       "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.1.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index 4ab6546..c76a3e5 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -11,7 +11,8 @@
     "check": "astro check"
   },
   "dependencies": {
-    "astro": "7.1.3"
+    "astro": "7.1.3",
+    "marked": "18.0.7"
   },
   "devDependencies": {
     "@astrojs/check": "0.9.9",
@@ -22,4 +23,3 @@
     "npm": ">=9.6.5"
   }
 }
-
diff --git a/frontend/src/content/java/xlil.md b/frontend/src/content/java/xlil.md
new file mode 100644
index 0000000..3ff0d3e
--- /dev/null
+++ b/frontend/src/content/java/xlil.md
@@ -0,0 +1,74 @@
+# XLIL for Java
+
+`org.xsslang:xlil:2026.1` is the official Java 25 binding for the stable
+XLIL C ABI. It can construct, verify, emit, parse, and inspect XLIL v0
+modules without maintaining a second Java parser.
+
+## Add the dependency
+
+The X# Gradle platform selects the official Java repository. Application
+builds do not add a Maven repository URL directly.
+
+```kotlin
+plugins {
+    id("java")
+    id("org.xsslang.platform") version "26.1"
+}
+
+repositories {
+    mavenCentral()
+
+    xsslangPlatform {
+        repositories()
+    }
+}
+
+dependencies {
+    xsslangPlatform {
+        implementation("org.xsslang:xlil:2026.1")
+    }
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(25))
+    }
+}
+```
+
+Enable FFM native access for modular applications:
+
+```text
+--enable-native-access=org.xsslang.xlil
+```
+
+The installed `xs_lil` shared library must be discoverable through the
+platform's normal native-library search rules.
+
+## Write XLIL
+
+```java
+try (XlilWriter writer = XlilWriter.create("Example")) {
+    XlilFunctionWriter main =
+        writer.defineFunction("main", XlilType.I32, List.of());
+    XlilBlockWriter entry = main.block("entry");
+    XlilValue exitCode = entry.constI32(0);
+    entry.returnValue(exitCode);
+
+    writer.verify();
+    System.out.print(writer.emit());
+}
+```
+
+## Read XLIL
+
+```java
+XlilModule module = XlilReader.parse("Example.xlil", source);
+System.out.println(module.name());
+module.functions().forEach(function -> System.out.println(function.name()));
+```
+
+The reader delegates parsing and verification to `libxs_lil` and returns
+immutable Java snapshots. `CString` helpers are available from
+`org.xsslang.ffi.c` for other Java 25 FFM integrations.
+
diff --git a/frontend/src/pages/java/index.astro b/frontend/src/pages/java/index.astro
new file mode 100644
index 0000000..a9288e7
--- /dev/null
+++ b/frontend/src/pages/java/index.astro
@@ -0,0 +1,76 @@
+---
+// SPDX-FileCopyrightText: 2026 Leitwolf <xs-lang.chess031@slmails.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import Icon from "../../components/Icon.astro";
+import SiteLayout from "../../layouts/SiteLayout.astro";
+---
+
+<SiteLayout
+  title="X# Java Repository"
+  description="Official read-only Java packages for X# and XLIL integration."
+>
+  <section class="repository-surface">
+    <div class="ambient" aria-hidden="true">
+      <span class="ambient-orb ambient-orb-a"></span>
+      <span class="ambient-orb ambient-orb-b"></span>
+    </div>
+    <header class="repository-header glass-panel">
+      <a class="brand" href="https://xsharp-lang.xyz/" aria-label="X# home">
+        <img class="brand-mark" src="/xsharp-logo.webp" width="38" height="38" alt="" />
+        <span class="brand-name">X#</span>
+        <span class="brand-channel">Java repository</span>
+      </a>
+      <a class="repository-source" href="https://github.com/xss-lang/xs-project" target="_blank" rel="noreferrer">
+        <Icon name="github" />
+        Source
+      </a>
+    </header>
+
+    <main class="repository-main repository-catalog">
+      <div class="repository-status glass-panel">
+        <span class="repository-status-icon"><Icon name="check" /></span>
+        Read-only repository online
+      </div>
+      <p class="eyebrow">Official Java packages</p>
+      <h1>Native XLIL.<br /><em>Java 25.</em></h1>
+      <p class="repository-lede">
+        Versioned Java libraries backed by stable X# native ABIs. Package publishing is restricted to
+        X# maintainers; repository users have read-only access.
+      </p>
+
+      <section class="package-list" aria-labelledby="packages-heading">
+        <div class="package-list-heading">
+          <div>
+            <p class="eyebrow">Packages</p>
+            <h2 id="packages-heading">Available now</h2>
+          </div>
+          <span>1 package</span>
+        </div>
+        <a class="package-card glass-panel" href="xlil/">
+          <span class="package-icon"><Icon name="registers" /></span>
+          <span class="package-copy">
+            <strong>XLIL</strong>
+            <code>org.xsslang:xlil</code>
+            <small>Java 25 FFM reader and writer for the XLIL C ABI.</small>
+          </span>
+          <span class="package-version">2026.1</span>
+          <span class="package-arrow"><Icon name="arrow" /></span>
+        </a>
+      </section>
+
+      <div class="repository-note glass-panel">
+        <Icon name="modules" />
+        <div>
+          <strong>Publishing is maintainer-only</strong>
+          <span>This host exposes immutable Maven-compatible artifacts and does not accept user uploads.</span>
+        </div>
+      </div>
+    </main>
+
+    <footer class="repository-footer">
+      <span>java.xsharp-lang.xyz</span>
+      <span>Official read-only repository</span>
+    </footer>
+  </section>
+</SiteLayout>
diff --git a/frontend/src/pages/java/xlil/index.astro b/frontend/src/pages/java/xlil/index.astro
new file mode 100644
index 0000000..d587903
--- /dev/null
+++ b/frontend/src/pages/java/xlil/index.astro
@@ -0,0 +1,75 @@
+---
+// SPDX-FileCopyrightText: 2026 Leitwolf <xs-lang.chess031@slmails.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { marked } from "marked";
+import Icon from "../../../components/Icon.astro";
+import SiteLayout from "../../../layouts/SiteLayout.astro";
+import xlilReadme from "../../../content/java/xlil.md?raw";
+
+const renderedReadme = await marked.parse(xlilReadme);
+---
+
+<SiteLayout
+  title="XLIL for Java · X# Java Repository"
+  description="Java 25 FFM reader and writer bindings for the stable XLIL C ABI."
+>
+  <section class="repository-surface">
+    <div class="ambient" aria-hidden="true">
+      <span class="ambient-orb ambient-orb-a"></span>
+      <span class="ambient-orb ambient-orb-b"></span>
+    </div>
+    <header class="repository-header glass-panel">
+      <a class="brand" href="../" aria-label="X# Java repository">
+        <img class="brand-mark" src="/xsharp-logo.webp" width="38" height="38" alt="" />
+        <span class="brand-name">X#</span>
+        <span class="brand-channel">Java repository</span>
+      </a>
+      <a class="repository-source" href="../" aria-label="Back to packages">
+        <Icon name="modules" />
+        Packages
+      </a>
+    </header>
+
+    <main class="repository-main package-detail">
+      <header class="package-detail-header">
+        <span class="package-icon package-icon-large"><Icon name="registers" /></span>
+        <div>
+          <p class="eyebrow">org.xsslang:xlil</p>
+          <h1>XLIL</h1>
+          <p>Java 25 · FFM · version 2026.1</p>
+        </div>
+      </header>
+
+      <div class="package-detail-grid">
+        <article class="markdown-body glass-panel" set:html={renderedReadme}></article>
+        <aside class="package-sidebar">
+          <section class="glass-panel">
+            <p class="eyebrow">Latest release</p>
+            <strong>2026.1</strong>
+            <span>Java 25 or newer</span>
+          </section>
+          <section class="glass-panel">
+            <p class="eyebrow">Artifacts</p>
+            <a href="/org/xsslang/xlil/2026.1/xlil-2026.1.jar">JAR</a>
+            <a href="/org/xsslang/xlil/2026.1/xlil-2026.1-sources.jar">Sources</a>
+            <a href="/org/xsslang/xlil/2026.1/xlil-2026.1-javadoc.jar">Javadoc</a>
+            <a href="/org/xsslang/xlil/2026.1/xlil-2026.1.pom">POM</a>
+          </section>
+          <section class="glass-panel package-read-only">
+            <Icon name="check" />
+            <div>
+              <strong>Read-only</strong>
+              <span>User uploads are disabled.</span>
+            </div>
+          </section>
+        </aside>
+      </div>
+    </main>
+
+    <footer class="repository-footer">
+      <span>java.xsharp-lang.xyz/xlil</span>
+      <span>Rendered from package Markdown</span>
+    </footer>
+  </section>
+</SiteLayout>
diff --git a/frontend/src/styles/global.css b/frontend/src/styles/global.css
index 1542c5a..77afc2b 100644
--- a/frontend/src/styles/global.css
+++ b/frontend/src/styles/global.css
@@ -224,6 +224,263 @@ body {
   font-size: 0.7rem;
 }
 
+.repository-catalog {
+  padding-block: 5.5rem;
+}
+
+.package-list {
+  width: min(48rem, 100%);
+  margin-top: 3.5rem;
+}
+
+.package-list-heading {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  margin-bottom: 1rem;
+}
+
+.package-list-heading .eyebrow {
+  margin-bottom: 0.35rem;
+}
+
+.package-list-heading h2 {
+  margin: 0;
+  font-size: clamp(1.45rem, 3vw, 2rem);
+}
+
+.package-list-heading > span {
+  color: var(--quiet);
+  font-family: var(--font-code);
+  font-size: 0.75rem;
+}
+
+.package-card {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto auto;
+  gap: 1rem;
+  align-items: center;
+  padding: 1.15rem;
+  border-radius: 1.15rem;
+  color: var(--ink);
+  text-decoration: none;
+  transition:
+    border-color 180ms ease,
+    background-color 180ms ease,
+    transform 180ms ease;
+}
+
+.package-card:hover {
+  border-color: rgb(198 156 255 / 45%);
+  background: rgb(48 37 67 / 72%);
+  transform: translateY(-2px);
+}
+
+.package-icon {
+  display: grid;
+  place-items: center;
+  width: 3rem;
+  height: 3rem;
+  border: 1px solid rgb(198 156 255 / 28%);
+  border-radius: 0.9rem;
+  color: var(--violet-bright);
+  background: linear-gradient(145deg, rgb(169 112 255 / 22%), rgb(109 231 221 / 8%));
+}
+
+.package-icon .icon {
+  width: 1.35rem;
+  height: 1.35rem;
+}
+
+.package-copy {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+}
+
+.package-copy strong {
+  font-size: 1.05rem;
+}
+
+.package-copy code,
+.package-version {
+  color: var(--cyan);
+  font-family: var(--font-code);
+  font-size: 0.76rem;
+}
+
+.package-copy small {
+  margin-top: 0.35rem;
+  overflow: hidden;
+  color: var(--quiet);
+  font-size: 0.78rem;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.package-arrow {
+  color: var(--quiet);
+  transform: rotate(45deg);
+}
+
+.package-arrow .icon {
+  width: 1rem;
+  height: 1rem;
+}
+
+.package-detail {
+  display: block;
+  padding-block: 4.5rem;
+}
+
+.package-detail-header {
+  display: flex;
+  gap: 1.25rem;
+  align-items: center;
+  margin-bottom: 2.5rem;
+}
+
+.package-detail-header h1 {
+  margin: 0.15rem 0;
+  font-size: clamp(2.5rem, 6vw, 4.75rem);
+}
+
+.package-detail-header p {
+  margin: 0;
+  color: var(--quiet);
+}
+
+.package-icon-large {
+  width: 4.5rem;
+  height: 4.5rem;
+  border-radius: 1.25rem;
+}
+
+.package-icon-large .icon {
+  width: 2rem;
+  height: 2rem;
+}
+
+.package-detail-grid {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 16rem;
+  gap: 1rem;
+  align-items: start;
+}
+
+.markdown-body {
+  min-width: 0;
+  padding: clamp(1.25rem, 4vw, 2.5rem);
+  border-radius: 1.25rem;
+  color: var(--muted);
+  line-height: 1.75;
+}
+
+.markdown-body > :first-child {
+  margin-top: 0;
+}
+
+.markdown-body > :last-child {
+  margin-bottom: 0;
+}
+
+.markdown-body h1,
+.markdown-body h2,
+.markdown-body h3 {
+  color: var(--ink);
+  font-family: var(--font-body);
+  letter-spacing: -0.02em;
+}
+
+.markdown-body h1 {
+  font-size: clamp(1.8rem, 4vw, 2.5rem);
+}
+
+.markdown-body h2 {
+  margin-top: 2.5rem;
+  padding-bottom: 0.6rem;
+  border-bottom: 1px solid rgb(255 255 255 / 9%);
+  font-size: 1.35rem;
+}
+
+.markdown-body a {
+  color: var(--cyan);
+}
+
+.markdown-body code {
+  border-radius: 0.35rem;
+  color: var(--cyan);
+  background: rgb(109 231 221 / 8%);
+  font-family: var(--font-code);
+  font-size: 0.86em;
+}
+
+.markdown-body :not(pre) > code {
+  padding: 0.15rem 0.35rem;
+}
+
+.markdown-body pre {
+  max-width: 100%;
+  overflow-x: auto;
+  padding: 1rem;
+  border: 1px solid rgb(255 255 255 / 8%);
+  border-radius: 0.85rem;
+  background: rgb(4 3 8 / 72%);
+  line-height: 1.55;
+}
+
+.markdown-body pre code {
+  color: #ded8eb;
+  background: transparent;
+}
+
+.package-sidebar {
+  display: grid;
+  gap: 0.75rem;
+}
+
+.package-sidebar > section {
+  display: flex;
+  gap: 0.45rem;
+  padding: 1rem;
+  border-radius: 1rem;
+  flex-direction: column;
+}
+
+.package-sidebar strong {
+  font-size: 1rem;
+}
+
+.package-sidebar span {
+  color: var(--quiet);
+  font-size: 0.76rem;
+}
+
+.package-sidebar a {
+  color: var(--cyan);
+  font-family: var(--font-code);
+  font-size: 0.8rem;
+  text-decoration: none;
+}
+
+.package-sidebar a:hover {
+  text-decoration: underline;
+}
+
+.package-sidebar .package-read-only {
+  flex-direction: row;
+  align-items: center;
+}
+
+.package-read-only > .icon {
+  color: var(--cyan);
+}
+
+.package-read-only div {
+  display: flex;
+  flex-direction: column;
+}
+
 a {
   color: inherit;
 }
@@ -1328,6 +1585,14 @@ footer a {
 }
 
 @media (max-width: 64rem) {
+  .package-detail-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .package-sidebar {
+    grid-template-columns: repeat(3, 1fr);
+  }
+
   .hero {
     grid-template-columns: 1fr;
     padding-top: 5rem;
@@ -1357,6 +1622,27 @@ footer a {
 }
 
 @media (max-width: 48rem) {
+  .package-card {
+    grid-template-columns: auto minmax(0, 1fr) auto;
+  }
+
+  .package-version {
+    grid-column: 2;
+  }
+
+  .package-arrow {
+    grid-column: 3;
+    grid-row: 1 / 3;
+  }
+
+  .package-copy small {
+    white-space: normal;
+  }
+
+  .package-sidebar {
+    grid-template-columns: 1fr;
+  }
+
   .repository-main {
     padding: 5rem 0;
   }
@@ -1461,6 +1747,19 @@ footer a {
 }
 
 @media (max-width: 35rem) {
+  .package-detail-header {
+    align-items: flex-start;
+  }
+
+  .package-icon-large {
+    width: 3.5rem;
+    height: 3.5rem;
+  }
+
+  .markdown-body {
+    padding: 1rem;
+  }
+
   .repository-header .brand-channel {
     display: none;
   }