Improve peripheral documentation readability

projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md

@@ -1,9 +1,21 @@
-# Advanced Items
+---
+peripheralInterface: AdvancedDigitizer
+---
+
+# Advanced Digitizer
+
+<div class="di-peripheral-hero di-peripheral-hero--advanced">
+  <div class="di-peripheral-image"><img src="../../../core/src/main/resources/assets/digitalitems/textures/block/advanced_digitizer_front_on.png" alt="Advanced digitizer block" /></div>
+  <div><span class="di-eyebrow">MULTI-STORAGE PERIPHERAL</span><p>The advanced digitizer moves items, fluids, and energy between attached storage and durable digital identifiers.</p><dl><div><dt>Peripheral type</dt><dd><code>advanced_digitizer</code></dd></div><div><dt>Storage</dt><dd>Items, fluids, energy</dd></div><div><dt>Failure style</dt><dd>Recoverable result pairs</dd></div></dl></div>
+</div>
 
 The advanced digitizer can extract from its internal inventory with source
 `self`, or from an attached inventory/item storage by peripheral name. The
 source defaults to `self`.
 
+> **Mode matters:** an identifier belongs to exactly one of `item`, `fluid`, or
+> `energy`. Always use the same mode when inspecting, refreshing, or restoring it.
+
 Item filters may be:
 
 - A one-based slot number. This requires slotted storage.

projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md

@@ -1,8 +1,20 @@
+---
+peripheralInterface: Digitizer
+---
+
 # Basic Digitizer
 
-The basic digitizer handles items in its own inventory. Slots are one-based and
-default to slot 1. `digitize()` removes the complete stack; `digitizeAmount()`
-requires an exact positive amount no greater than the physical stack.
+<div class="di-peripheral-hero">
+  <div class="di-peripheral-image"><img src="../../../core/src/main/resources/assets/digitalitems/textures/block/digitizer_front_on.png" alt="Digitizer block" /></div>
+  <div><span class="di-eyebrow">ITEM PERIPHERAL</span><p>The basic digitizer turns physical item stacks into portable digital identifiers and restores them through its internal inventory.</p><dl><div><dt>Peripheral type</dt><dd><code>digitizer</code></dd></div><div><dt>Storage</dt><dd>Items</dd></div><div><dt>Failure style</dt><dd>Lua errors</dd></div></dl></div>
+</div>
+
+Slots are one-based and default to slot 1. `digitize()` removes the complete
+stack; `digitizeAmount()` requires an exact positive amount no greater than the
+physical stack.
+
+> **Inherited inventory API:** `size`, `list`, `getItemDetail`, `getItemLimit`,
+> `pushItems`, and `pullItems` are also available on this peripheral.
 
 ## Round trip a partial stack
 
@@ -29,6 +41,8 @@ local inserted = digitizer.rematerializeAmount(id, 8)
 print("Inserted " .. inserted)
 ```
 
+## Errors and remaining items
+
 All failures throw. Empty slots, non-positive amounts, requesting more than the
 physical or digital count, and unknown or decayed identifiers are errors.
 

projects/typed-peripheral-digitalitems/documentation/index.md

@@ -1,23 +1,34 @@
-# Digital Items Typed Peripheral API
+# Digital Items Peripheral Manual
 
-This package supplies TypeScriptToLua declarations and peripheral providers for
-Digital Items 3. It covers the item-only `digitizer` and the multi-storage
-`advanced_digitizer` peripherals.
+Player-focused documentation and typed APIs for the Digital Items 3 peripherals.
+Use these pages whether you write programs directly in CraftOS Lua or compile
+TypeScript with TypeScriptToLua.
 
-## Choose a peripheral
+## Choose your digitizer
 
-- Use the basic digitizer for simple item workflows through its internal inventory.
-- Use the advanced digitizer to address remote item, fluid, or energy storage, merge content into existing identifiers, and handle recoverable failures.
-- Both peripherals inherit inventory methods. The advanced digitizer additionally reports decay and stack limits through `getConfiguration()`.
+<div class="di-peripheral-grid">
+  <a class="di-peripheral-card" href="guides/basic-digitizer.md">
+    <span class="di-peripheral-image"><img src="../../core/src/main/resources/assets/digitalitems/textures/block/digitizer_front_on.png" alt="Digitizer block" /></span>
+    <span class="di-peripheral-copy"><strong>Digitizer</strong><small>Peripheral type: <code>digitizer</code></small><span>Digitize and restore items through a simple internal inventory.</span><b>Open peripheral guide &rarr;</b></span>
+  </a>
+  <a class="di-peripheral-card di-peripheral-card--advanced" href="guides/advanced-items.md">
+    <span class="di-peripheral-image"><img src="../../core/src/main/resources/assets/digitalitems/textures/block/advanced_digitizer_front_on.png" alt="Advanced digitizer block" /></span>
+    <span class="di-peripheral-copy"><strong>Advanced Digitizer</strong><small>Peripheral type: <code>advanced_digitizer</code></small><span>Move items, fluids, and energy between remote storage and digital IDs.</span><b>Open peripheral guide &rarr;</b></span>
+  </a>
+</div>
 
-## Documentation
+Both peripherals include the standard CC:Tweaked inventory methods. The advanced
+digitizer also exposes configured decay and storage limits through
+`getConfiguration()`.
+
+## Start here
 
 - [Getting started](getting-started.md)
 - [Digital identifiers](digital-identifiers.md)
 - [Basic digitizer guide](guides/basic-digitizer.md)
 - [Advanced item guide](guides/advanced-items.md)
 - [Fluid and energy guide](guides/fluids-and-energy.md)
 
-The generated API reference documents every exported type, method overload, and
-provider. Guide examples are shown first in TypeScriptToLua and then in direct
-CraftOS Lua.
+The **Guides** explain behavior in player terms and include both Lua and
+TypeScript examples. The **API reference** is the precise source for signatures,
+overloads, return types, and provider declarations.

projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css

@@ -62,6 +62,7 @@ body {
 
 .col-content {
   position: relative;
+  max-width: 920px;
 }
 
 .col-content::before {
@@ -209,6 +210,222 @@ th, td {
   display: none !important;
 }
 
+.col-content p,
+.col-content li {
+  max-width: 78ch;
+}
+
+.col-content table {
+  width: 100%;
+  border-collapse: collapse;
+  overflow: hidden;
+}
+
+.col-content th {
+  color: var(--di-accent-hover);
+  background: var(--di-bg-elevated);
+  text-align: left;
+}
+
+.col-content th,
+.col-content td {
+  padding: 0.8rem 1rem;
+  border-bottom: 1px solid var(--di-border-subtle);
+  vertical-align: top;
+}
+
+.col-content blockquote {
+  margin: 1.5rem 0;
+  padding: 0.8rem 1.1rem;
+  border-left: 4px solid var(--color-ts-number);
+  background: color-mix(in srgb, var(--color-ts-number) 7%, var(--di-bg-secondary));
+}
+
+.col-content blockquote p {
+  margin: 0;
+}
+
+.di-peripheral-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1rem;
+  margin: 1.5rem 0 2rem;
+}
+
+.di-peripheral-card,
+.di-peripheral-hero {
+  border: 1px solid var(--di-border);
+  background: linear-gradient(145deg, var(--di-bg-elevated), var(--di-bg-secondary));
+}
+
+.di-peripheral-card {
+  display: flex;
+  gap: 1.2rem;
+  min-height: 190px;
+  padding: 1.25rem;
+  border-radius: 10px;
+  color: var(--color-text);
+  text-decoration: none;
+  transition: border-color 160ms ease, transform 160ms ease;
+}
+
+.di-peripheral-card:hover {
+  border-color: var(--di-accent-hover);
+  color: var(--color-text);
+  transform: translateY(-3px);
+}
+
+.di-peripheral-card--advanced,
+.di-peripheral-hero--advanced {
+  border-color: color-mix(in srgb, var(--color-ts-number) 35%, transparent);
+}
+
+.di-peripheral-image {
+  display: grid;
+  flex: 0 0 128px;
+  min-height: 128px;
+  place-items: center;
+  border-radius: 6px;
+  background-color: #0a1114;
+  background-image: linear-gradient(45deg, rgba(255,255,255,.035) 25%, transparent 25%, transparent 75%, rgba(255,255,255,.035) 75%), linear-gradient(45deg, rgba(255,255,255,.035) 25%, transparent 25%, transparent 75%, rgba(255,255,255,.035) 75%);
+  background-position: 0 0, 8px 8px;
+  background-size: 16px 16px;
+}
+
+.di-peripheral-image img {
+  width: 112px;
+  height: 112px;
+  image-rendering: pixelated;
+}
+
+.di-peripheral-copy {
+  display: flex;
+  flex-direction: column;
+}
+
+.di-peripheral-copy strong {
+  font-size: 1.25rem;
+}
+
+.di-peripheral-copy small {
+  margin: 0.25rem 0 0.75rem;
+  color: var(--di-text-secondary);
+}
+
+.di-peripheral-copy b {
+  margin-top: auto;
+  color: var(--di-accent-hover);
+  font-size: 0.82rem;
+}
+
+.di-peripheral-hero {
+  display: grid;
+  grid-template-columns: 176px minmax(0, 1fr);
+  gap: 1.75rem;
+  margin: 1rem 0 2rem;
+  padding: 1.5rem;
+  border-radius: 10px;
+}
+
+.di-peripheral-hero .di-peripheral-image {
+  min-height: 176px;
+}
+
+.di-peripheral-hero .di-peripheral-image img {
+  width: 144px;
+  height: 144px;
+}
+
+.di-eyebrow {
+  color: var(--color-ts-number);
+  font: 700 0.7rem/1 "Lucida Console", Monaco, monospace;
+  letter-spacing: 0.12em;
+}
+
+.di-peripheral-hero p {
+  margin: 0.55rem 0 1rem;
+  font-size: 1.05rem;
+}
+
+.di-peripheral-hero dl {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0.7rem;
+  margin: 0;
+}
+
+.di-peripheral-hero dl div {
+  min-width: 0;
+}
+
+.di-peripheral-hero dt {
+  color: var(--di-text-secondary);
+  font-size: 0.68rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.di-peripheral-hero dd {
+  margin: 0.2rem 0 0;
+  overflow-wrap: anywhere;
+  font-weight: 650;
+}
+
+.di-method-reference {
+  margin-top: 3rem;
+}
+
+.di-generated-note {
+  margin-bottom: 1.25rem;
+  color: var(--di-text-secondary);
+  font-size: 0.9rem;
+}
+
+.di-method-card {
+  margin: 1rem 0;
+  border: 1px solid var(--di-border);
+  border-radius: 8px;
+  background: var(--di-bg-secondary);
+  box-shadow: 0 8px 22px rgba(0, 0, 0, 0.1);
+  overflow: hidden;
+}
+
+.di-method-card > h3 {
+  margin: 0;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--di-border);
+  background: var(--di-bg-elevated);
+  color: var(--di-accent-hover);
+  font-size: 1rem;
+}
+
+.di-method-overload {
+  padding: 1rem;
+}
+
+.di-method-overload + .di-method-overload {
+  border-top: 1px dashed var(--di-border);
+}
+
+.di-method-overload .tsd-signature {
+  margin: 0 0 1rem;
+  padding: 0.8rem;
+  box-shadow: none;
+  overflow-x: auto;
+}
+
+.di-method-overload .tsd-comment {
+  margin: 0.75rem 0;
+}
+
+.di-method-overload h4 {
+  margin: 1rem 0 0.35rem;
+  color: var(--di-text-secondary);
+  font-size: 0.78rem;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+}
+
 .di-version-panel {
   margin: 0.5rem 0 1rem;
   padding: 0.6rem 0.75rem;
@@ -332,4 +549,34 @@ footer {
     max-width: 100%;
     overflow-x: auto;
   }
+
+  .di-peripheral-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .di-peripheral-hero {
+    grid-template-columns: 1fr;
+  }
+
+  .di-peripheral-hero .di-peripheral-image {
+    min-height: 144px;
+  }
+
+  .di-peripheral-hero dl {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+@media (max-width: 480px) {
+  .di-peripheral-card {
+    flex-direction: column;
+  }
+
+  .di-peripheral-image {
+    flex-basis: auto;
+  }
+
+  .di-peripheral-hero dl {
+    grid-template-columns: 1fr;
+  }
 }