Skip to content

Commit e7c6d95

Browse files
farukalpayfarukalpay
committed
XML
1 parent f76984d commit e7c6d95

25 files changed

+869
-2
lines changed

‎.DS_Store‎

6 KB
Binary file not shown.

‎README.md‎

Lines changed: 88 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,88 @@
1-
# xml-lib
2-
XML-Lib is an over-engineered XML playground with a canonical lifecycle, a guardrail subsystem, Hilbert-backed proofs, and PPTX workflow docs. Use it to trace document phases, reason about enforcement math, and reference detailed presentation pipelines—all in one repository.
1+
# XML-Lib
2+
3+
XML-Lib is a deliberately over-engineered playground for experimenting with XML workflows, mathematical guardrails, and auxiliary tooling. The repository contains:
4+
5+
- A canonical XML lifecycle (`lib/*.xml`) that flows from bootstrapping through governance.
6+
- A guardrail subsystem with charter, middle-phase engineering, and archival handoffs (`lib/guardrails`).
7+
- A math-heavy engine that proves the guardrail properties using Banach/Hilbert machinery (`lib/engine`).
8+
- Documentation for presentation (PPTX) pipelines (`document/pptx`) plus end-to-end XML examples in the repo root.
9+
10+
Whether you need a reference flow for XML documents, want to inspect a formal proof of guardrail consistency, or need guidance for a PPTX build system, XML-Lib keeps everything in one place.
11+
12+
## Repository Layout
13+
14+
```
15+
├── lib
16+
│ ├── begin.xml … continuum.xml # Primary XML lifecycle
17+
│ ├── guardrails/ # Guardrail charter → middle → end
18+
│ └── engine/ # Axioms, operators, proofs, Hilbert stack
19+
├── document/pptx # Presentation engineering docs
20+
├── example_document.xml # Straightforward lifecycle demo
21+
└── example_amphibians.xml # Overly engineered amphibian dossier
22+
```
23+
24+
## XML Lifecycle (`lib/*.xml`)
25+
26+
| Phase | Description |
27+
| --- | --- |
28+
| `lib/begin.xml` | Establishes the initial document intent and commentary. |
29+
| `lib/start.xml` | Adds references, XML-engineering guidelines, and sets up iteration rules. |
30+
| `lib/iteration.xml` | Describes per-cycle steps, telegraphs scheduling, and enforces schema contracts. |
31+
| `lib/end.xml` | Aggregates iteration outputs, validates schema/checksum, and archives the final bundle. |
32+
| `lib/continuum.xml` | Extends the lifecycle with governance, telemetry, simulations, policies, and hand-offs. |
33+
34+
These files are intentionally verbose so you can trace how data should flow through each phase. Downstream artifacts (guardrails, proofs, PPTX docs) reference this chain to stay consistent.
35+
36+
## Guardrail Subsystem (`lib/guardrails`)
37+
38+
The guardrail directory mirrors the lifecycle but focuses on enforcement:
39+
40+
1. `begin.xml` – Sets the guardrail charter, scope boundaries, and invariants.
41+
2. `middle.xml` – Performs the heavy engineering lift: fixed-point modeling, policy transpilers, simulators, telemetry routers, validation matrices, and control loops.
42+
3. `end.xml` – Seals the guardrail assets with checksums, artifacts, and multi-role sign-offs.
43+
44+
Each file references the core lifecycle to ensure every policy/enforcement artifact inherits the same intent.
45+
46+
## Mathematical Engine (`lib/engine`)
47+
48+
The engine formalizes guardrail behavior:
49+
50+
- `spaces.xml`, `hilbert.xml`, `operators.xml` – Define the underlying Banach/Hilbert spaces, norms, projections, resolvents, and contraction operators.
51+
- `axioms.xml`, `proof.xml` – Capture the logical foundations and end-to-end proofs tying guardrails-begin → guardrails-middle → guardrails-end.
52+
- `hilbert/` – Contains a blueprint, layered decompositions, operator addenda, fixed-point proofs, and an index for easy navigation.
53+
54+
Use these files to reason about fixed points, Fejér monotone sequences, and energy bounds when evolving the guardrail workflows.
55+
56+
## Presentation Engineering Docs (`document/pptx`)
57+
58+
This folder documents how to analyze, build, or edit PowerPoint decks using XML-Lib tooling:
59+
60+
- `architecture.xml` – Overview of modules (analysis, html builds, OOXML editing, template remix) and dependencies.
61+
- `workflows.xml` – Step-by-step instructions for each workflow, including required commands and example scripts.
62+
- `checks.xml` – Guardrails to keep HTML authoring, validation, and governance aligned with the rest of the repo.
63+
64+
All guidance is freshly written and respects proprietary constraints; use it as a playbook when working with `.pptx` assets.
65+
66+
## Example Documents
67+
68+
- `example_document.xml` – Walks through each lifecycle phase, showing how to combine templates with custom payloads.
69+
- `example_amphibians.xml` – A richly layered scenario (taxonomy, telemetry, governance) that exercises every artifact including guardrails and continuum governance.
70+
71+
Use these as references when crafting new XML bundles or onboarding teammates.
72+
73+
## Working With XML-Lib
74+
75+
1. **Start with the lifecycle** – Read `lib/begin.xml` through `lib/continuum.xml` to understand the canonical flow.
76+
2. **Study guardrails** – Inspect `lib/guardrails/*` to see how policies, simulators, and checksums tie into the lifecycle.
77+
3. **Consult the engine** – When modifying guardrails or adding new enforcement logic, update the proofs in `lib/engine`/`lib/engine/hilbert` so the math matches.
78+
4. **Leverage PPTX docs** – For presentation work, follow the instructions in `document/pptx` to analyze, build, or remix decks safely.
79+
5. **Reference examples** – Use the example XML documents to validate assumptions or prototype new scenarios.
80+
81+
## Contributing
82+
83+
1. Keep XML ASCII-friendly unless a file already uses Unicode.
84+
2. When touching guardrails or engine files, maintain the references between begin/middle/end and update proofs if invariants change.
85+
3. For PPTX tooling, never reuse proprietary text; follow the documented workflows.
86+
4. Add tests, proofs, or documentation snippets whenever you extend functionality to keep the repo self-explanatory.
87+
88+
Pull requests should explain how they interact with the lifecycle, guardrails, proofs, or PPTX documentation to keep future maintenance straightforward.

‎document/pptx/architecture.xml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<pptx-architecture>
2+
<commenet>Engineering-focused reference for presentation operations</commenet>
3+
<scope>
4+
<boundary>Only reuse mechanics from existing XML-Lib artifacts; wording is freshly authored.</boundary>
5+
<folder>document/pptx</folder>
6+
</scope>
7+
<modules>
8+
<module id="analysis">
9+
<objective>Extract and inspect slide data without mutating the binary packages.</objective>
10+
<tools>
11+
<tool>python -m markitdown path/to/file.pptx &gt; notes.md</tool>
12+
<tool>python skills/pptx/ooxml/scripts/unpack.py deck.pptx tmp/unpacked</tool>
13+
</tools>
14+
<outputs>Markdown transcripts, raw XML snapshots (ppt/slides/*.xml, theme files, media index).</outputs>
15+
</module>
16+
<module id="creation-plain">
17+
<objective>Generate decks from scratch using html2pptx conversion.</objective>
18+
<inputs>Slide outlines, shared CSS variables, HTML fragments per slide, js driver.</inputs>
19+
<guards>Must read html2pptx.md entirely before invoking any builder.</guards>
20+
</module>
21+
<module id="editing-ooxml">
22+
<objective>Modify existing decks by manipulating unpacked XML.</objective>
23+
<requirement>Always run validate.py before re-packaging to avoid corrupt files.</requirement>
24+
</module>
25+
<module id="template-driven">
26+
<objective>Reuse template decks by rearranging, inventorying, and replacing text content.</objective>
27+
<pipeline>thumbnail analysis → template inventory → outline mapping → rearrange.py → inventory.py → replacement-text.json → replace.py</pipeline>
28+
</module>
29+
</modules>
30+
<dependencies>
31+
<dependency>skills/pptx/html2pptx.tgz for html conversion.</dependency>
32+
<dependency>pptxgenjs global install for script driver.</dependency>
33+
<dependency>LibreOffice + Poppler for PDF/thumbnail workflows.</dependency>
34+
</dependencies>
35+
</pptx-architecture>

‎document/pptx/checks.xml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<pptx-checks>
2+
<commenet>Guardrails for presentation workflows</commenet>
3+
<category name="preflight">
4+
<item>Always read html2pptx.md or ooxml.md entirely before touching their workflows.</item>
5+
<item>Verify NODE_PATH resolves to npm root before running the JS builder.</item>
6+
<item>Confirm markitdown, pptxgenjs, playwright, react-icons, LibreOffice, and Poppler are installed.</item>
7+
</category>
8+
<category name="authoring">
9+
<item>Shared CSS file may only declare custom properties; no selectors or classes.</item>
10+
<item>Slides must use row/col/fit helpers (no flexbox) and semantic headings/lists.</item>
11+
<item>Placeholders for charts/tables require gray background plus class="placeholder".</item>
12+
</category>
13+
<category name="validation">
14+
<item>Thumbnail grid review looks for cutoff text, overlap, margins, and contrast problems.</item>
15+
<item>replace.py clears every shape not explicitly set in replacement JSON—verify shape lists carefully.</item>
16+
<item>validate.py must pass before repacking OOXML edits.</item>
17+
</category>
18+
<category name="governance">
19+
<item>Log checksums or control-plane hashes when exporting final decks to align with guardrails-end workflows.</item>
20+
<item>Reference hilbert fixed-point proofs when reasoning about iterative guardrail enforcement on PPTX pipelines.</item>
21+
</category>
22+
</pptx-checks>

‎document/pptx/workflows.xml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
<pptx-workflows>
2+
<commenet>Detailed middle-focused procedures for PPTX engineering</commenet>
3+
4+
<workflow id="analysis">
5+
<goal>Read presentation content without altering it.</goal>
6+
<steps>
7+
<step order="1">Convert deck text to markdown using markitdown for quick triage.</step>
8+
<step order="2">Unzip with skills/pptx/ooxml/scripts/unpack.py into a scratch directory.</step>
9+
<step order="3">Inspect ppt/presentation.xml for slide ordering and metadata.</step>
10+
<step order="4">Check ppt/slides/slideN.xml plus notesSlides, comments, layouts, masters, and theme files for styling intel.</step>
11+
<step order="5">Use grep/rg to search for color nodes (&lt;a:solidFill&gt;, &lt;a:srgbClr&gt;) or font nodes (&lt;a:fontScheme&gt;).</step>
12+
</steps>
13+
</workflow>
14+
15+
<workflow id="build-from-html">
16+
<goal>Create a brand-new presentation without templates.</goal>
17+
<prechecks>
18+
<check>Read html2pptx.md from start to finish—no skipping.</check>
19+
<check>Ensure npm global install: npm list -g @ant/html2pptx || npm install -g skills/pptx/html2pptx.tgz.</check>
20+
<check>Confirm pptxgenjs, playwright, and markitdown are present.</check>
21+
</prechecks>
22+
<phases>
23+
<phase name="planning">
24+
<action>Define deck tone, palette, typography, and slide-by-slide outline with layout + speaker note descriptions.</action>
25+
</phase>
26+
<phase name="css">
27+
<action>Create shared CSS file containing only custom property declarations for colors, fonts, spacing.</action>
28+
</phase>
29+
<phase name="html">
30+
<action>Author one HTML file per slide (e.g., 960×540 body) embedding the shared CSS via &lt;style&gt;, using row/col/fit helpers, semantic headings/lists, placeholders for charts/tables, and CSS variables for every color/font.</action>
31+
</phase>
32+
<phase name="conversion">
33+
<action>Run NODE_PATH=\"$(npm root -g)\" node scripts/build-deck.js 2&gt;&amp;1 to convert HTML via html2pptx.</action>
34+
<code language="javascript"><![CDATA[
35+
const PptxGen = require("pptxgenjs");
36+
const { html2pptx } = require("@ant/html2pptx");
37+
38+
async function build() {
39+
const deck = new PptxGen();
40+
deck.layout = "LAYOUT_16x9";
41+
42+
await html2pptx("slides/slide1.html", deck);
43+
const { slide, placeholders } = await html2pptx("slides/slide2.html", deck);
44+
slide.addChart(deck.charts.LINE, chartData, placeholders[0]);
45+
46+
await deck.writeFile("output.pptx");
47+
}
48+
49+
build().catch(console.error);
50+
]]></code>
51+
</phase>
52+
<phase name="validation">
53+
<action>Generate thumbnails via python scripts/thumbnail.py output.pptx thumbs --cols 4 and inspect for clipping/contrast/spacing; iterate until clean.</action>
54+
</phase>
55+
</phases>
56+
</workflow>
57+
58+
<workflow id="edit-ooxml">
59+
<goal>Modify an existing deck at the XML layer.</goal>
60+
<steps>
61+
<step order="1">Read ooxml.md completely.</step>
62+
<step order="2">Unpack: python skills/pptx/ooxml/scripts/unpack.py deck.pptx work/unpacked.</step>
63+
<step order="3">Edit ppt/slides/slideN.xml, layouts, masters, theme, etc., as needed.</step>
64+
<step order="4">Validate after each logical chunk: python skills/pptx/ooxml/scripts/validate.py work/unpacked --original deck.pptx.</step>
65+
<step order="5">Repack when clean: python skills/pptx/ooxml/scripts/pack.py work/unpacked deck-new.pptx.</step>
66+
</steps>
67+
</workflow>
68+
69+
<workflow id="template-remix">
70+
<goal>Build a new deck from a template while preserving design intent.</goal>
71+
<steps>
72+
<step order="1">Extract template text via python -m markitdown template.pptx &gt; template-content.md and read fully.</step>
73+
<step order="2">Generate thumbnail grids: python scripts/thumbnail.py template.pptx analysis --cols 4.</step>
74+
<step order="3">Author template-inventory.md enumerating every slide (index, layout, purpose).</step>
75+
<step order="4">Write outline.md mapping your new content sections to template slide indices (0-based).</step>
76+
<step order="5">Use scripts/rearrange.py template.pptx working.pptx idx0,idx1,... to duplicate/reorder slides.</step>
77+
<step order="6">Extract text inventory: python scripts/inventory.py working.pptx text-inventory.json and study the full JSON (no slicing).</step>
78+
<step order="7">Prepare replacement-text.json referencing actual slide/shape ids, copying necessary paragraph properties (bullets, alignment, fonts, colors, spacing).</step>
79+
<step order="8">Apply replacements: python scripts/replace.py working.pptx replacement-text.json output.pptx; fix any validation overflow errors reported.</step>
80+
</steps>
81+
</workflow>
82+
83+
</pptx-workflows>

‎example_amphibians.xml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
<amphibian-project>
2+
<meta>
3+
<species-focus>Axolotl, Poison Dart Frog, Tiger Salamander</species-focus>
4+
<mission>Modeling lifecycle transformations for amphibian habitat dossiers.</mission>
5+
</meta>
6+
<lifecycle>
7+
<phase id="bootstrap">
8+
<template path="lib/begin.xml">Seed dossier headers and taxonomic roots.</template>
9+
<taxonomy>
10+
<order>Caudata</order>
11+
<order>Anura</order>
12+
</taxonomy>
13+
<controls>
14+
<control name="hydration-profile" type="gradient">humid->semi-aquatic</control>
15+
</controls>
16+
</phase>
17+
<phase id="activation">
18+
<template path="lib/start.xml">Apply engineering guardrails before iteration.</template>
19+
<stack>
20+
<layer name="schema-alignment">Enforce shared nodes between begin and start docs.</layer>
21+
<layer name="hydration-simulator">Bind rainfall deltas to dataset v2.</layer>
22+
<layer name="nutrient-budget">Budget mg/day provisioning.</layer>
23+
</stack>
24+
</phase>
25+
<phase id="iterations">
26+
<template path="lib/iteration.xml">Execute multi-pass environmental tuning.</template>
27+
<iteration-matrix>
28+
<axis name="species">
29+
<value>Axolotl</value>
30+
<value>PoisonDartFrog</value>
31+
<value>TigerSalamander</value>
32+
</axis>
33+
<axis name="habitat">
34+
<value>Wetland</value>
35+
<value>CloudForest</value>
36+
<value>CaptiveLab</value>
37+
</axis>
38+
<scenario id="s-phase">
39+
<steps>
40+
<step path="lib/start.xml">Rehydrate baseline for scenario.</step>
41+
<step path="lib/iteration.xml">Run param sweep for micro-climate.</step>
42+
<step path="lib/iteration.xml">Persist iteration snapshot for telemetry.</step>
43+
</steps>
44+
</scenario>
45+
</iteration-matrix>
46+
</phase>
47+
<phase id="termination">
48+
<template path="lib/end.xml">Finalize the amphibian dossier bundle.</template>
49+
<archival>
50+
<artifact type="pdf">dossiers/amphibians.pdf</artifact>
51+
<artifact type="dataset">datasets/amphibian-readings.csv</artifact>
52+
</archival>
53+
<validation>
54+
<rule>All specimens have hydration > 75%</rule>
55+
<rule>Every iteration snapshot has QA sign-off.</rule>
56+
</validation>
57+
</phase>
58+
<phase id="governance">
59+
<template path="lib/continuum.xml">Project future habitat engineering.</template>
60+
<control-plane>
61+
<policy-ref>lib/continuum.xml/control-plane/policies/policy[@id='quarantine']</policy-ref>
62+
<checksum-ref>lib/continuum.xml/control-plane/checksums/checksum[@type='schema']</checksum-ref>
63+
</control-plane>
64+
<telemetry-overlay>
65+
<stream name="salinity-drift" units="ppt">Track deviations per habitat.</stream>
66+
<stream name="molt-success" units="percent">Ensure success > 95%.</stream>
67+
</telemetry-overlay>
68+
</phase>
69+
</lifecycle>
70+
<engineering-layers>
71+
<layer name="data-vault">
72+
<source path="lib/begin.xml">Taxonomic constants.</source>
73+
<source path="lib/iteration.xml">Iteration snapshots.</source>
74+
</layer>
75+
<layer name="policy-engine">
76+
<module path="lib/start.xml">Schema contracts.</module>
77+
<module path="lib/continuum.xml">Runtime policies.</module>
78+
</layer>
79+
<layer name="release-orchestrator">
80+
<module path="lib/end.xml">Final archive operations.</module>
81+
<module path="lib/continuum.xml">Telemetry watchers.</module>
82+
</layer>
83+
</engineering-layers>
84+
<appendices>
85+
<appendix id="A">
86+
<title>Hydration Matrix</title>
87+
<dataset source="lib/iteration.xml">Normalized hydration results per species.</dataset>
88+
</appendix>
89+
<appendix id="B">
90+
<title>Governance Checklist</title>
91+
<checklist source="lib/continuum.xml">Control-plane requirements for amphibian rollouts.</checklist>
92+
</appendix>
93+
</appendices>
94+
</amphibian-project>

‎example_document.xml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<document>
2+
<meta>
3+
<title>Sample XML lifecycle</title>
4+
<description>Demonstrates how to walk through XML-Lib artifacts.</description>
5+
</meta>
6+
<phases>
7+
<phase name="begin">
8+
<use path="lib/begin.xml">Load canonical bootstrap directives.</use>
9+
<payload>
10+
<note>Custom header content injected after begin.xml template.</note>
11+
</payload>
12+
</phase>
13+
<phase name="start">
14+
<use path="lib/start.xml">Apply start-phase engineering constraints.</use>
15+
<payload>
16+
<note>Set iteration envelope to 3 cycles.</note>
17+
</payload>
18+
</phase>
19+
<phase name="iteration">
20+
<use path="lib/iteration.xml">Execute per-cycle workflow.</use>
21+
<payload>
22+
<iteration id="alpha">Transform dataset A.</iteration>
23+
<iteration id="beta">Transform dataset B.</iteration>
24+
</payload>
25+
</phase>
26+
<phase name="end">
27+
<use path="lib/end.xml">Finalize the archive and validations.</use>
28+
<payload>
29+
<note>Attach QA sign-off ticket #42.</note>
30+
</payload>
31+
</phase>
32+
<phase name="continuum">
33+
<use path="lib/continuum.xml">Extend lifecycle into governance plane.</use>
34+
<payload>
35+
<telemetry override="true">Enable latency and throughput streams.</telemetry>
36+
<simulation-mode>stress</simulation-mode>
37+
</payload>
38+
</phase>
39+
</phases>
40+
<summary>
41+
<status>complete</status>
42+
<next-action>Monitor telemetry for 24h before public release.</next-action>
43+
</summary>
44+
</document>

‎lib/begin.xml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<begin>
2+
<commenet>Begin the document</commenet>
3+
</begin>

0 commit comments

Comments
 (0)