@geml/geml 1.7.6 → 1.7.8

package/dist/render.js

@@ -562,17 +562,27 @@ export class RenderCtx {
                         return `<figure${idAttr}><p class="table-note">external data <code>${esc(src)}</code> — loaded at render time</p>${cap0}</figure>`;
                     }
                 }
+                // Overflow FOLDS; it is never dropped. `--to html` is a CONVERSION, and
+                // a conversion that loses data is not one — the old behaviour kept the
+                // first 500 lines and said "the complete data is in the document
+                // source", which is no help at all to someone holding only the HTML.
+                // The bound belongs to what is OPEN, not to what is present: the rest
+                // sits in a collapsed <details>, so the page is exactly as short as
+                // before and the block is complete. There is no ceiling above which
+                // lines vanish again, because a <pre> is a single text node — the cost
+                // of keeping them is bytes on disk, which is what not losing data
+                // costs.
                 const tail = fmt === "jsonl" && lines.length > limit;
                 const shown = tail ? lines.slice(-limit) : lines.slice(0, limit);
-                const omitted = lines.length - shown.length;
-                const note = omitted > 0
-                    ? `<p class="table-note">${tail
-                        ? `showing the last ${shown.length} of ${lines.length} lines — earlier lines are in the document source`
-                        : `showing the first ${shown.length} of ${lines.length} lines — the complete data is in the document source`}</p>`
-                    : "";
+                const rest = tail ? lines.slice(0, lines.length - shown.length) : lines.slice(shown.length);
                 const cap = caption ? `<figcaption>${esc(caption)}</figcaption>` : "";
-                const pre = `<pre class="data-src" data-format="${escAttr(fmt)}">${esc(shown.join("\n"))}</pre>`;
-                return `<figure${idAttr}>${tail ? note + pre : pre + note}${cap}</figure>`;
+                const pre = (ls) => `<pre class="data-src" data-format="${escAttr(fmt)}">${esc(ls.join("\n"))}</pre>`;
+                if (rest.length === 0)
+                    return `<figure${idAttr}>${pre(shown)}${cap}</figure>`;
+                // jsonl reads as an append-log, so its open end is the NEWEST lines and
+                // the fold holds the earlier ones, above; json reads from the top.
+                const more = `<details class="data-more"><summary>${rest.length} ${tail ? "earlier" : "more"} line${rest.length === 1 ? "" : "s"} of ${lines.length}</summary>${pre(rest)}</details>`;
+                return `<figure${idAttr}>${tail ? more + pre(shown) : pre(shown) + more}${cap}</figure>`;
             }
             case "table":
                 return b.table ? this.table(b.table, b.id, caption) : `<p class="render-error">table failed to parse</p>`;
@@ -636,17 +646,20 @@ export class RenderCtx {
     table(t, id, caption) {
         const idAttr = id ? ` id="${escAttr(id)}"` : "";
         const alignStyle = (a) => (a ? ` style="text-align:${a}"` : "");
-        // Parsing + laying out tens of thousands of <table> rows freezes the
-        // page for seconds, so the HTML view renders a bounded preview (the
-        // model keeps every row: charts, computed summaries and the code-graph
-        // never read the HTML). Codemap edge tables additionally fold shut —
-        // they are machine data; elsewhere the table is content and stays open.
-        // The codemap index's #modules table IS the page's content — the module
-        // inventory people scan and filter — so it renders in full. Edge tables
-        // (#calls / #called-by) stay previewed+folded: machine data at scale.
-        const maxRows = this.isCodemapDoc && id === "modules" ? Infinity : (this.opts.tableRows ?? 500);
+        // Laying out tens of thousands of <table> rows OPEN freezes the page for
+        // seconds, so a long table renders folded shut — the codemap's edge tables
+        // (#calls / #called-by) are the ones that get there. Its #modules table is
+        // the page's content, the inventory people came to scan and filter, so that
+        // one stays open at any size.
+        //
+        // EVERY row is rendered. `tableRows` bounds what is OPEN, never what is
+        // present: past it the whole table goes inside a collapsed <details>, which
+        // costs the reader one click and costs the document nothing. It used to
+        // slice the rows away and say the complete table was in the source, which
+        // made `--to html` a lossy conversion of a table the model holds in full.
+        const foldAbove = this.isCodemapDoc && id === "modules" ? Infinity : (this.opts.tableRows ?? 500);
         const allRows = t.rows;
-        const rows = allRows.length > maxRows ? allRows.slice(0, maxRows) : allRows;
+        const rows = allRows;
         const thead = t.header
             ? `<thead><tr>${t.columns.map((col, c) => `<th${alignStyle(t.align[c])}>${esc(col)}</th>`).join("")}</tr></thead>`
             : "";
@@ -666,15 +679,10 @@ export class RenderCtx {
             : "";
         const cap = caption ? `<figcaption>${esc(caption)}</figcaption>` : "";
         const tools = `<div class="table-tools"><input class="table-filter" type="search" placeholder="Filter rows…" aria-label="Filter table rows"></div>`;
-        if (allRows.length > maxRows) {
-            const note = `<p class="table-note">showing the first ${maxRows} of ${allRows.length} rows — the complete table is in the document source</p>`;
-            if (this.isCodemapDoc) {
-                const summary = `${esc(id ? "#" + id : "table")} · ${allRows.length} rows (preview: first ${maxRows})`;
-                return `<figure class="table-figure"${idAttr}><details><summary>${summary}</summary>${tools}` +
-                    `<div class="table-scroll"><table class="geml-table">${thead}<tbody>\n${bodyRows}\n</tbody>${tfoot}</table></div>${note}</details>${cap}</figure>`;
-            }
-            return `<figure class="table-figure"${idAttr}>${tools}` +
-                `<div class="table-scroll"><table class="geml-table">${thead}<tbody>\n${bodyRows}\n</tbody>${tfoot}</table></div>${note}${cap}</figure>`;
+        if (allRows.length > foldAbove) {
+            const summary = `${esc(id ? "#" + id : "table")} · ${allRows.length} rows`;
+            return `<figure class="table-figure"${idAttr}><details><summary>${summary}</summary>${tools}` +
+                `<div class="table-scroll"><table class="geml-table">${thead}<tbody>\n${bodyRows}\n</tbody>${tfoot}</table></div></details>${cap}</figure>`;
         }
         return `<figure class="table-figure"${idAttr}>${tools}` +
             `<div class="table-scroll"><table class="geml-table">${thead}<tbody>\n${bodyRows}\n</tbody>${tfoot}</table></div>${cap}</figure>`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geml/geml",
-  "version": "1.7.6",
+  "version": "1.7.8",
   "mcpName": "io.github.geml-spec/geml",
   "publishConfig": {
     "access": "public"

package/skill/SKILL.md

@@ -53,6 +53,23 @@ file stay what it is.
 If `geml --version` does not answer, none of this is available. Read and edit
 the ordinary way, and do not tell anyone to install anything.
 
+## A project moving TO GEML
+
+"This project's documents are GEML now" means new documents are authored as
+`.geml` — notes, plans, findings, reports — in one directory (`docs/geml/`
+unless the project says otherwise), one file per topic, with an `index.geml`
+saying what is there and why. It does not mean converting what is already
+written, and nobody has to say "leave the existing files alone" for that to
+hold.
+
+**Add, never replace.** Writing a `.geml` version of a document is not licence
+to delete the Markdown it was drawn from — however completely the content was
+carried across, and whatever a "one home per topic" convention seems to imply.
+Deleting a file is a request a person makes, never an inference from a
+convention. When both exist, say in each what it is for and name one of them as
+the place a given fact is maintained: two documents describing a project is
+fine, two documents maintaining the same fact is what drifts.
+
 ## A GEML document — get the syntax right
 
 GEML expresses **every** kind of structured content — code, tables, diagrams,
@@ -75,9 +92,12 @@ GEML file is correct only when `geml check` reports **no error diagnostics**
    `---` breaks, no YAML frontmatter — metadata is a `=== meta` block, and the
    document TITLE lives there (`title = "…"`), not in an H1. A heading may
    carry a stable explicit id: `## Title {#sec}`.
-4. **Every `#id` is unique per document**, and **every reference must
-   resolve** — `[t](#id)`, `[[#id]]`, `[^id]`, `src=`, `data=`,
-   `other.geml#id`. An unresolved reference is a build **error**.
+4. **Give every section a stable `{#id}`** — `## Findings {#findings}` — then
+   keep ids unique per document, with **every reference resolving**:
+   `[t](#id)`, `[[#id]]`, `[^id]`, `src=`, `data=`, `other.geml#id`. An
+   unresolved reference is a build **error**. Naming them is the part that pays
+   later: a document with no ids costs what Markdown costs, because there is
+   nothing for `geml get` to read or `geml set` to replace short of the file.
 5. **No raw HTML.** Notes → `=== note`, comments → `%%` lines, hidden content
    → `{hidden}`, addressable prose → `=== text`, verified data → `=== data`
    (json/jsonl; `code` shows text, `data` IS data).
@@ -108,38 +128,21 @@ geml find    "text" file|dir          # search block CONTENT -> file<TAB>address
                                       # a directory walks *.geml only
 geml get     file.geml '#id'          # read ONE block (a heading id = its whole section)
 geml set     file.geml '#id' --in f   # replace ONE block (re-parsed; never writes a broken doc)
-geml replace file.geml OLD NEW        # EXPERIMENTAL literal swap; --within '#id' to narrow
 geml history save file.geml -m "…"    # snapshot to .gemlhistory after each meaningful edit
 geml revert  file.geml '#id'          # roll ONE block back (--rev -2 | changed | <rev-id>)
 ```
 
 Address a block, never a line range: `#id` · `'## Heading'` (its whole section)
-· `'=== type'` · `@<hex>` (no id) · `L27` or `L27-58` (the smallest block holding
-those lines — how a line number from an editor, a linter or a diff hunk becomes
-an address). `list` and `find` print addresses that paste straight into the
-others, so neither `grep` nor a line count is needed to locate anything.
-
-Any section can be cut three ways, on `get` and `set` alike: `--head` (the
-heading line), `--intro` (what it says before its first subheading — empty when
-one follows immediately, the whole body when none does), `--body` (everything
-under it, so it always contains the intro). `--intro` is how you edit a
-section's opening without pulling its subsections into context, and setting an
-empty one writes an opening where the section had none.
-
-When the exact old text is already known and nothing needs reading — a version
-string in six places, a renamed term — `geml replace` is the cheap path, and the
-one to prefer over dropping to `sed`: same two short strings, but the result is
-re-parsed before it lands, the blocks it touched are named back to you, and it
-is in `.gemlhistory` to revert. It swaps a LITERAL, never a pattern, and refuses
-a swap that would rename an id (use `geml rename`, which fixes the references
-too). **It is EXPERIMENTAL and may be withdrawn** — reach for it, but do not
-build anything on it that cannot change.
-
-A write is refused when it would break the document, never merely because it
-removes something: a replacement that drops blocks is carried out and NAMED on
-stderr — unnamed blocks included — with `geml revert` as the way back. Read,
-edit, write back, and nothing is dropped, because `get` handed those blocks to
-you. Send content that omits them only when removing them is the point.
+· `L27-58` (the smallest block holding those lines — how a line number from an
+editor, a linter or a diff hunk becomes an address). `list` and `find` print
+addresses that paste straight into the others, so neither `grep` nor a line
+count is needed to locate anything.
+
+The rest is one `geml get` away in the reference below, and stays there because
+it is needed rarely and this page is read every time: the remaining address
+forms in `#cli`, and in `#editing` the three ways to cut a section
+(`--head`/`--intro`/`--body`), the experimental `replace`, and what a write that
+drops blocks does.
 
 ## Full reference — pull ONE section, not the whole file
 

package/skill/references/authoring.geml

@@ -293,6 +293,28 @@ geml revert file.geml '#intro' --rev changed  # …the block's last ACTUAL chang
 block) and `history`/`revert` (version and rewind it) let an agent revise a
 document incrementally and undo any single section.
 
+**A section can be cut three ways**, on `get` and `set` alike: `--head` (the
+heading line), `--intro` (what it says before its first subheading — empty when
+one follows immediately, the whole body when none does), `--body` (everything
+under it, so it always contains the intro). `--intro` is how you edit a
+section's opening without pulling its subsections into context, and setting an
+empty one writes an opening where the section had none.
+
+**When the exact old text is already known** and nothing needs reading — a
+version string in six places, a renamed term — `geml replace` is the cheap path,
+and the one to prefer over dropping to `sed`: the same two short strings, but
+the result is re-parsed before it lands, the blocks it touched are named back to
+you, and it is in `.gemlhistory` to revert. It swaps a LITERAL, never a pattern,
+and refuses a swap that would rename an id (use `geml rename`, which fixes the
+references too). **It is EXPERIMENTAL and may be withdrawn** — reach for it, but
+do not build anything on it that cannot change.
+
+**A write is refused when it would BREAK the document**, never merely because it
+removes something: a replacement that drops blocks is carried out and NAMED on
+stderr — unnamed blocks included — with `geml revert` as the way back. Read,
+edit, write back, and nothing is dropped, because `get` handed those blocks to
+you. Send content that omits them only when removing them is the point.
+
 **Where sidecars do NOT belong:** a doc that git already versions — config
 docs especially — usually needs no `.gemlhistory`; do not create one there
 unless the user asks for finer-than-commit history.