@u84u/gl 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,334 @@
+Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution 4.0 International Public License ("Public License"). To the
+extent this Public License may be interpreted as a contract, You are
+granted the Licensed Rights in consideration of Your acceptance of
+these terms and conditions, and the Licensor grants You such rights in
+consideration of benefits the Licensor receives from making the
+Licensed Material available under these terms and conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+  Rights that is derived from or based upon the Licensed Material and
+  in which the Licensed Material is translated, altered, arranged,
+  transformed, or otherwise modified in a manner requiring permission
+  under the Copyright and Similar Rights held by the Licensor. For
+  purposes of this Public License, where the Licensed Material is a
+  musical work, performance, or sound recording, Adapted Material is
+  always produced where the Licensed Material is synched in timed
+  relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+  and Similar Rights in Your contributions to Adapted Material in
+  accordance with the terms and conditions of this Public License.
+
+  c. Copyright and Similar Rights means copyright and/or similar
+  rights closely related to copyright including, without limitation,
+  performance, broadcast, sound recording, and Sui Generis Database
+  Rights, without regard to how the rights are labeled or categorized.
+  For purposes of this Public License, the rights specified in
+  Section 2(b)(1)-(2) are not Copyright and Similar Rights.
+
+  d. Effective Technological Measures means those measures that, in
+  the absence of proper authority, may not be circumvented under laws
+  fulfilling obligations under Article 11 of the WIPO Copyright Treaty
+  adopted on December 20, 1996, and/or similar international
+  agreements.
+
+  e. Exceptions and Limitations means fair use, fair dealing, and/or
+  any other exception or limitation to Copyright and Similar Rights
+  that applies to Your use of the Licensed Material.
+
+  f. Licensed Material means the artistic or literary work, database,
+  or other material to which the Licensor applied this Public License.
+
+  g. Licensed Rights means the rights granted to You subject to the
+  terms and conditions of this Public License, which are limited to
+  all Copyright and Similar Rights that apply to Your use of the
+  Licensed Material and that the Licensor has authority to license.
+
+  h. Licensor means the individual(s) or entity(ies) granting rights
+  under this Public License.
+
+  i. Share means to provide material to the public by any means or
+  process that requires permission under the Licensed Rights, such as
+  reproduction, public display, public performance, distribution,
+  dissemination, communication, or importation, and to make material
+  available to the public including in ways that members of the public
+  may access the material from a place and at a time individually
+  chosen by them.
+
+  j. Sui Generis Database Rights means rights other than copyright
+  resulting from Directive 96/9/EC of the European Parliament and of
+  the Council of 11 March 1996 on the legal protection of databases,
+  as amended and/or succeeded, as well as other essentially equivalent
+  rights anywhere in the world.
+
+  k. You means the individual or entity exercising the Licensed Rights
+  under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in
+          Section 6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section
+          2(a)(4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes
+          or may be construed as permission to assert or imply that
+          You are, or that Your use of the Licensed Material is,
+          connected with, or sponsored, endorsed, or granted official
+          status by, the Licensor or others designated to receive
+          attribution as provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases, the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may
+          be reasonable to satisfy the conditions by providing a URI
+          or hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+       4. If You Share Adapted Material You produce, the Adapter's
+          License You apply must not prevent recipients of the
+          Adapted Material from complying with this Public License.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, but not its individual contents, is Adapted Material;
+     and
+
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+  EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+  AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY
+  KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, IMPLIED,
+  STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, WARRANTIES
+  OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+  NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR
+  THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT KNOWN OR
+  DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT ALLOWED IN
+  FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+  TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+  NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+  INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+  COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+  USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN ADVISED
+  OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES.
+  WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR IN PART,
+  THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+  above shall be interpreted in a manner that, to the extent possible,
+  most closely approximates an absolute disclaimer and waiver of all
+  liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+  Similar Rights licensed here. However, if You fail to comply with
+  this Public License, then Your rights under this Public License
+  terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated
+  under Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured,
+          provided it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. Where the Licensor may also offer the Licensed Material under
+  separate terms or conditions or stop distributing the Licensed
+  Material at any time; however, doing so will not terminate this
+  Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+  License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+  terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+  Licensed Material not stated herein are separate from and
+  independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+  shall not be interpreted to, reduce, limit, restrict, or impose
+  conditions on any use of the Licensed Material that could lawfully
+  be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License
+  is deemed unenforceable, it shall be automatically reformed to the
+  minimum extent necessary to make it enforceable. If the provision
+  cannot be reformed, it shall be severed from this Public License
+  without affecting the enforceability of the remaining terms and
+  conditions.
+
+  c. No term or condition of this Public License will be waived and
+  no failure to comply consented to unless expressly agreed to by the
+  Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+  to be a limitation upon, or waiver of, any privileges and immunities
+  that apply to the Licensor or You, including from the legal
+  processes of any jurisdiction or authority.
+
+
+Creative Commons is not a party to its public licenses.
+Notwithstanding, Creative Commons may elect to apply one of its public
+licenses to material it publishes and in those instances will be
+considered the “Licensor.” The text of the Creative Commons public
+licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or
+logo of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any other arrangements, understandings, or agreements concerning
+use of licensed material. For the avoidance of doubt, this paragraph
+does not form part of the public licenses.
+
+Creative Commons may be contacted at creativecommons.org.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @u84u/gl
 
-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.
+Compile `gl`, a statically-typed shading language, to GLSL (450 core, ES 3.00) or WGSL.
+
+## Install
+
+Not on npm. Install from GitHub:
+
+```bash
+npm install github:u84u/gl
+```
+
+## CLI
+
+```bash
+gl <input.gl> [--target=glsl|wgsl] [--output=<file>] [--format] [--check]
+```
+
+See `LANGUAGE.md` for the full language reference, shader stages, imports, and built-ins.
+
+## Library API
+
+```ts
+import { compileSync } from "@u84u/gl";
+
+const result = compileSync({
+  target: "wgsl",
+  source: `fn main(): vec4 { return vec4(1.0, 0.0, 0.0, 1.0) }`,
+  file: "shader.gl",
+});
+
+if (result.diagnostics.some((d) => d.severity === "error")) {
+  // handle diagnostics
+} else {
+  // result.code is the legacy single-output convenience path
+  // result.shaders contains the complete artifact list with reflection
+  console.log(result.shaders[0]?.code);
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `target` | `string` | Backend target ID: `"glsl"`, `"glsl-450"`, `"glsl-es-300"`, `"wgsl"` (or a custom registered target) |
+| `file` | `string` | Source file identity for diagnostics |
+| `sourceId` | `string` | Stable canonical identity for the main source (defaults to `file`) |
+| `source` | `string` | Source text to parse and compile (mutually exclusive with `ast`) |
+| `ast` | `Program` | Pre-built AST to type-check and codegen (mutually exclusive with `source`) |
+| `resolver` | `SourceResolver` | Required for `compileAsync` when source contains imports |
+| `registry` | `BackendRegistry` | Optional backend registry (defaults to the shared default registry) |
+| `provenance` | `Map<Statement, string>` | Maps statements to source files for imported-module diagnostics |
+
+### Entry points
+
+- `compileSync(options)` — sync; no imports in source. Returns `CompileResult`.
+- `compileAsync(options)` — async; `resolver` required when source contains imports. Returns `Promise<CompileResult>`.
+- `compile(options)` — deprecated alias for `compileSync`.
+
+### CompileResult
+
+```ts
+interface CompileResult {
+  code: string | null;        // convenience: first shader's code, or null
+  shaders: ShaderArtifact[];  // full artifact list with code, stage, entry point, reflection
+  ast: Program;               // type-checked program
+  diagnostics: Diagnostic[];  // structured diagnostics
+  target: string;             // resolved target ID
+}
+```
+
+Each `ShaderArtifact` includes `stage`, `entryPoint`, `code`, and `reflection` (entry points, resources, uniforms).
+
+### Shader reflection
+
+`ShaderReflection` includes:
+- `entryPoints`: entry point name, stage, inputs (params with name/type), outputs (return values with name/type/location/builtin)
+- `resources`: every binding with `kind` ("sampler"/"sampledTexture"/"uniform"/"uniformBuffer"), `binding`, `set`, `stageVisibility`. GLSL non-sampler bindings are reported as standalone `"uniform"` declarations; WGSL `var<uniform>` bindings are reported as `"uniformBuffer"`. Synthesized sampler bindings for texture bindings are included (WGSL) with the binding actually emitted by codegen.
+- `uniforms`: uniform declarations with `name`, `type`, `offset`, `size`. GLSL standalone uniforms each have `offset: 0`; WGSL uniform buffers are sized using WGSL uniform address-space layout rules.
+
+### Backend capability enforcement
+
+Backends reject unsupported features with structured diagnostics instead of silently narrowing types:
+- `WGSL_UNSUPPORTED_SCALAR`, `WGSL_UNSUPPORTED_STAGE`, `WGSL_UNSUPPORTED_RESOURCE`, `WGSL_UNSUPPORTED_MATRIX`
+- `GLSL_UNSUPPORTED_SCALAR`, `GLSL_UNSUPPORTED_STAGE`, `GLSL_UNSUPPORTED_RESOURCE`
+
+Validation checks shader stages, scalar types, and resource kinds against each backend's `BackendCapabilities`.
+
+### Custom backends
+
+Backends register themselves in a `BackendRegistry`. Use `createDefaultBackendRegistry()` to copy the built-in registry, then `registry.register(backend)` or `registry.replace(backend)` to add or override targets. Pass your registry via `options.registry`.
+
+Package entry points: `@u84u/gl` (core), `@u84u/gl/node` (filesystem resolver), `@u84u/gl/browser` (fetch resolver), `@u84u/gl/cli`.
+
+## Development
+
+```bash
+npm install          # dependencies
+npm run build        # tsup bundle to dist/ (ESM)
+npm run typecheck    # tsc --noEmit (strict)
+npm test             # vitest — full test suite
+npm run validate     # build & run C shader validator (needs libOSMesa, libGL)
+```
+
+## License
+
+CC BY 4.0

package/dist/browser/resolver.d.ts

@@ -0,0 +1,23 @@
+import { S as SourceResolver, a as SourceModule } from '../resolver-Fn4_IKEu.js';
+
+/**
+ * Browser source resolver. Resolves `.gl` import specifiers relative to the
+ * importing module's canonical URL using `fetch`.
+ *
+ * All network I/O is confined to this adapter; the compiler core never
+ * accesses `fetch`, `window`, or `navigator`.
+ */
+declare class FetchSourceResolver implements SourceResolver {
+    /** Base URL used to resolve relative import specifiers. */
+    readonly baseUrl: string;
+    /** Optional fetch implementation (defaults to global fetch). */
+    private readonly fetchFn;
+    constructor(
+    /** Base URL used to resolve relative import specifiers. */
+    baseUrl: string, 
+    /** Optional fetch implementation (defaults to global fetch). */
+    fetchFn?: typeof fetch);
+    resolve(specifier: string, importer: SourceModule): Promise<SourceModule>;
+}
+
+export { FetchSourceResolver };

package/dist/browser/resolver.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+// src/browser/resolver.ts
+var FetchSourceResolver = class {
+  constructor(baseUrl, fetchFn = fetch) {
+    this.baseUrl = baseUrl;
+    this.fetchFn = fetchFn;
+  }
+  baseUrl;
+  fetchFn;
+  async resolve(specifier, importer) {
+    const importerUrl = new URL(importer.id, this.baseUrl);
+    const resolvedUrl = new URL(specifier, importerUrl.href);
+    let response;
+    try {
+      response = await this.fetchFn(resolvedUrl.href);
+    } catch (err) {
+      throw new Error(
+        `Failed to fetch imported module "${specifier}" from ${resolvedUrl.href}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch imported module "${specifier}": HTTP ${response.status} ${response.statusText}`
+      );
+    }
+    const source = await response.text();
+    return {
+      id: resolvedUrl.href,
+      displayName: specifier,
+      source
+    };
+  }
+};
+export {
+  FetchSourceResolver
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }